feat(specification-storage): implement endpoints to manage field definitions

.spectral.yaml

@@ -1,4 +1,4 @@
-extends: [ "spectral:oas" ]
+extends: [[spectral:oas, all]]
 aliases:
   PathItem:
     description: ''
@@ -58,6 +58,10 @@ aliases:
           - "$.paths[*][*].requestBody.content[*]"
           - "$.paths[*][*].responses[*].content[*]"
 rules:
+  info-license: off
+  license-url: off
+  contact-properties: off
+  oas3-valid-media-example: off
   docs-descriptions:
     given:
       - "#DescribableObjects"
@@ -115,7 +119,7 @@ rules:
   docs-media-types-examples-or-schema:
     given:
       - "#MediaTypeObjects"
-    severity: info
+    severity: warn
     then:
       function: schema
       functionOptions:
@@ -124,8 +128,6 @@ rules:
           anyOf:
             - required:
                 - examples
-            - required:
-                - schema
     description: "Media object must contain a defined schema or examples."
     message: No example or schema provided for {{property}}
     formats:
@@ -154,4 +156,21 @@ rules:
       field: tags
     description: "Operation must have at least one tag."
     message: Operation should have non-empty `tags` array.
-
+  schema-fields-descriptions:
+    description: "Each field in schema should have description"
+    given: "$..[?(@ && @.properties)].properties.*"
+    severity: error
+    resolved: true
+    then:
+      - field: "description"
+        function: defined
+  schema-descriptions:
+    description: "Each schema should have description and title"
+    given: "$..[?(@ && @.properties)]"
+    severity: error
+    resolved: true
+    then:
+      - field: "description"
+        function: defined
+      - field: "title"
+        function: defined

NEWS.md

@@ -7,6 +7,7 @@
 #### Server
 * Specification Storage: implement endpoint to fetch specifications ([MRSPECS-3](https://folio-org.atlassian.net//browse/MRSPECS-3))
 * Specification Storage: implement endpoints to fetch specification rules and enable/disable it ([MRSPECS-4](https://folio-org.atlassian.net//browse/MRSPECS-4))
+* Specification Storage: implement endpoints to manage field definitions ([MRSPECS-6](https://folio-org.atlassian.net//browse/MRSPECS-4))
 #### General
 * Implement build dependants GitHub workflow on PR creation ([MRSPECS-9](https://folio-org.atlassian.net//browse/MRSPECS-9))
 

api/examples/request/specificationFieldChangeDto.yaml

@@ -0,0 +1,6 @@
+value:
+  tag: '888'
+  label: Custom Field - Contributor Data
+  url: http://www.example.org/field888.html
+  repeatable: true
+  required: true

api/examples/response/specificationDtoCollection.yaml

@@ -0,0 +1,25 @@
+value:
+  specifications:
+    - id: 6eefa4c6-bbf7-4845-ad82-de7fc4abd0e3
+      title: MARC Bibliographic Specification
+      family: MARC
+      profile: bibliographic
+      url: https://www.loc.gov/marc/bibliographic/
+      fields: []
+      rules: []
+      metadata:
+        createdDate: 2024-05-22 14:55:06
+        createdByUserId: 00000000-0000-0000-0000-000000000000
+        updatedDate: 2024-05-22 14:55:06
+        updatedByUserId: 00000000-0000-0000-0000-000000000000
+    - id: a37d01ba-75c7-4a0c-997e-309823f1df3f
+      title: MARC Authority Specification
+      family: MARC
+      profile: authority
+      url: https://www.loc.gov/marc/authority/
+      metadata:
+        createdDate: 2024-05-22 14:55:06
+        createdByUserId: 00000000-0000-0000-0000-000000000000
+        updatedDate: 2024-05-22 14:55:06
+        updatedByUserId: 00000000-0000-0000-0000-000000000000
+  totalRecords: 2

api/examples/response/specificationFieldDto.yaml

@@ -0,0 +1,15 @@
+value:
+  id: ff0780f9-573d-46ba-8bf1-73181052f4b4
+  specificationId: 6eefa4c6-bbf7-4845-ad82-de7fc4abd0e3
+  tag: '666'
+  label: Mystic Field
+  url: https://www.loc.gov/marc/bibliographic/bd666.html
+  repeatable: false
+  required: true
+  deprecated: false
+  scope: custom
+  metadata:
+    createdDate: 2024-05-22 14:55:06
+    createdByUserId: 00000000-0000-0000-0000-000000000000
+    updatedDate: 2024-05-22 15:30:42
+    updatedByUserId: 00000000-0000-0000-0000-000000000000

api/examples/response/specificationFieldDtoCollection.yaml

@@ -0,0 +1,45 @@
+value:
+  fields:
+    - id: ff0780f9-573d-46ba-8bf1-73181052f4b4
+      specificationId: 6eefa4c6-bbf7-4845-ad82-de7fc4abd0e3
+      tag: '001'
+      label: Control Number
+      url: https://www.loc.gov/marc/bibliographic/bd001.html
+      repeatable: false
+      required: true
+      deprecated: false
+      scope: system
+      metadata:
+        createdDate: 2024-05-22 14:55:06
+        createdByUserId: 00000000-0000-0000-0000-000000000000
+        updatedDate: 2024-05-22 15:30:42
+        updatedByUserId: 00000000-0000-0000-0000-000000000000
+    - id: 7f38eb68-31e5-47c0-8553-8dfcacf167bc
+      specificationId: 6eefa4c6-bbf7-4845-ad82-de7fc4abd0e3
+      tag: '270'
+      label: Address
+      url: https://www.loc.gov/marc/bibliographic/bd270.html
+      repeatable: true
+      required: false
+      deprecated: false
+      scope: defined
+      metadata:
+        createdDate: 2024-05-22 14:55:06
+        createdByUserId: 00000000-0000-0000-0000-000000000000
+        updatedDate: 2024-05-22 15:30:42
+        updatedByUserId: 00000000-0000-0000-0000-000000000000
+    - id: 0005d827-5be7-4bd3-b7ce-2a51a353d1ab
+      specificationId: 6eefa4c6-bbf7-4845-ad82-de7fc4abd0e3
+      tag: 'LDR'
+      label: Leader
+      url: https://www.loc.gov/marc/bibliographic/bdleader.html
+      repeatable: false
+      required: true
+      deprecated: false
+      scope: system
+      metadata:
+        createdDate: 2024-05-22 14:55:06
+        createdByUserId: 00000000-0000-0000-0000-000000000000
+        updatedDate: 2024-05-22 15:30:42
+        updatedByUserId: 00000000-0000-0000-0000-000000000000
+  totalRecords: 3

api/examples/response/specificationRuleDtoCollection.yaml

@@ -0,0 +1,137 @@
+value:
+  rules:
+    - id: 7c843a14-4c87-4c7d-9ad6-5c7654bff9b5
+      specificationId: 6eefa4c6-bbf7-4845-ad82-de7fc4abd0e3
+      name: Undefined Field
+      description: Field is not defined but exists in a record
+      code: undefinedField
+      enabled: true
+      metadata:
+        createdDate: 2024-05-22 14:55:06
+        createdByUserId: 00000000-0000-0000-0000-000000000000
+        updatedDate: 2024-05-22 14:55:06
+        updatedByUserId: 00000000-0000-0000-0000-000000000000
+    - id: b67da9f9-6f54-4727-9fd0-58a522a56fde
+      specificationId: 6eefa4c6-bbf7-4845-ad82-de7fc4abd0e3
+      name: Deprecated Field
+      description: Field is deprecated but exists in a record
+      code: deprecatedField
+      enabled: true
+      metadata:
+        createdDate: 2024-05-22 14:55:06
+        createdByUserId: 00000000-0000-0000-0000-000000000000
+        updatedDate: 2024-05-22 14:55:06
+        updatedByUserId: 00000000-0000-0000-0000-000000000000
+    - id: c1b80d56-5f6f-4c0e-92df-6d2356eb379f
+      specificationId: 6eefa4c6-bbf7-4845-ad82-de7fc4abd0e3
+      name: Non-Repeatable Field
+      description: Field is non-repeatable but exists more than once in a record
+      code: nonRepeatableField
+      enabled: true
+      metadata:
+        createdDate: 2024-05-22 14:55:06
+        createdByUserId: 00000000-0000-0000-0000-000000000000
+        updatedDate: 2024-05-22 14:55:06
+        updatedByUserId: 00000000-0000-0000-0000-000000000000
+    - id: db1f2423-037e-4ec9-9931-ff25ccbac917
+      specificationId: 6eefa4c6-bbf7-4845-ad82-de7fc4abd0e3
+      name: Missing Field
+      description: Field is required but does not exist in a record
+      code: missingField
+      enabled: true
+      metadata:
+        createdDate: 2024-05-22 14:55:06
+        createdByUserId: 00000000-0000-0000-0000-000000000000
+        updatedDate: 2024-05-22 14:55:06
+        updatedByUserId: 00000000-0000-0000-0000-000000000000
+    - id: 35675d8c-7753-4d74-9e8c-5ff749931f2a
+      specificationId: 6eefa4c6-bbf7-4845-ad82-de7fc4abd0e3
+      name: Invalid Field Value
+      description: Field is flat and contains an invalid value
+      code: invalidFieldValue
+      enabled: true
+      metadata:
+        createdDate: 2024-05-22 14:55:06
+        createdByUserId: 00000000-0000-0000-0000-000000000000
+        updatedDate: 2024-05-22 14:55:06
+        updatedByUserId: 00000000-0000-0000-0000-000000000000
+    - id: 3ec76c78-28c9-4c29-9439-19f8345e86db
+      specificationId: 6eefa4c6-bbf7-4845-ad82-de7fc4abd0e3
+      name: Invalid Indicator
+      description: Field contains specified indicators and codes but with invalid indicator
+        in the record
+      code: invalidIndicator
+      enabled: true
+      metadata:
+        createdDate: 2024-05-22 14:55:06
+        createdByUserId: 00000000-0000-0000-0000-000000000000
+        updatedDate: 2024-05-22 14:55:06
+        updatedByUserId: 00000000-0000-0000-0000-000000000000
+    - id: 108ca421-24ba-4dc2-8d0f-661c00667e9a
+      specificationId: 6eefa4c6-bbf7-4845-ad82-de7fc4abd0e3
+      name: Undefined Subfield
+      description: Subfield is not defined but exists in a record's field
+      code: undefinedSubfield
+      enabled: true
+      metadata:
+        createdDate: 2024-05-22 14:55:06
+        createdByUserId: 00000000-0000-0000-0000-000000000000
+        updatedDate: 2024-05-22 14:55:06
+        updatedByUserId: 00000000-0000-0000-0000-000000000000
+    - id: ceb0cfc7-d2b1-4358-829b-f7204f4305bd
+      specificationId: 6eefa4c6-bbf7-4845-ad82-de7fc4abd0e3
+      name: Deprecated Subfield
+      description: Subfield is deprecated but exists in a record's field
+      code: deprecatedSubfield
+      enabled: true
+      metadata:
+        createdDate: 2024-05-22 14:55:06
+        createdByUserId: 00000000-0000-0000-0000-000000000000
+        updatedDate: 2024-05-22 14:55:06
+        updatedByUserId: 00000000-0000-0000-0000-000000000000
+    - id: 1aa070fd-d2b5-4def-bf3d-699895f13b88
+      specificationId: 6eefa4c6-bbf7-4845-ad82-de7fc4abd0e3
+      name: Non-Repeatable Subfield
+      description: Subfield is non-repeatable but exists more than once in a record's
+        field
+      code: nonRepeatableSubfield
+      enabled: true
+      metadata:
+        createdDate: 2024-05-22 14:55:06
+        createdByUserId: 00000000-0000-0000-0000-000000000000
+        updatedDate: 2024-05-22 14:55:06
+        updatedByUserId: 00000000-0000-0000-0000-000000000000
+    - id: 3cf61681-deb9-482c-beac-db8544fa3019
+      specificationId: 6eefa4c6-bbf7-4845-ad82-de7fc4abd0e3
+      name: Missing Subfield
+      description: Subfield is required but does not exist in a record's field
+      code: missingSubfield
+      enabled: true
+      metadata:
+        createdDate: 2024-05-22 14:55:06
+        createdByUserId: 00000000-0000-0000-0000-000000000000
+        updatedDate: 2024-05-22 14:55:06
+        updatedByUserId: 00000000-0000-0000-0000-000000000000
+    - id: 2182d955-c1e8-44b6-8f97-94b2b173244d
+      specificationId: 6eefa4c6-bbf7-4845-ad82-de7fc4abd0e3
+      name: Invalid Subfield Value
+      description: Subfield value is not valid based on subfield definition
+      code: invalidSubfieldValue
+      enabled: true
+      metadata:
+        createdDate: 2024-05-22 14:55:06
+        createdByUserId: 00000000-0000-0000-0000-000000000000
+        updatedDate: 2024-05-22 14:55:06
+        updatedByUserId: 00000000-0000-0000-0000-000000000000
+    - id: ed98f7ce-ee87-47a3-a509-367e3fae540f
+      specificationId: 6eefa4c6-bbf7-4845-ad82-de7fc4abd0e3
+      name: Non-Repeatable 1XX Field
+      description: More than one field from the 1XX group exists in a record
+      code: nonRepeatable1XXField
+      enabled: true
+      metadata:
+        createdDate: 2024-05-22 14:55:06
+        createdByUserId: 00000000-0000-0000-0000-000000000000
+        updatedDate: 2024-05-22 14:55:06
+        updatedByUserId: 00000000-0000-0000-0000-000000000000
+  totalRecords: 12

api/mod-record-specifications.yaml

@@ -27,12 +27,18 @@ servers:
 tags:
   - name: specification-storage
     description: Provides API for managing specifications.
+  - name: specification-storage-fields
+    description: Provides API for managing specification fields.
 
 
 paths:
   /specification-storage/specifications:
-    $ref: 'paths/specification-storage/get-specifications-path.yaml'
-  /specification-storage/specifications/{id}/rules:
-    $ref: 'paths/specification-storage/get-specification-rules-path.yaml'
-  /specification-storage/specifications/{id}/rules/{ruleId}:
-    $ref: 'paths/specification-storage/get-specification-rules-by-id-path.yaml'
+    $ref: 'paths/specification-storage/specifications-path.yaml'
+  /specification-storage/specifications/{specificationId}/rules:
+    $ref: 'paths/specification-storage/specification-rules-path.yaml'
+  /specification-storage/specifications/{specificationId}/rules/{id}:
+    $ref: 'paths/specification-storage/specification-rules-by-id-path.yaml'
+  /specification-storage/specifications/{specificationId}/fields:
+    $ref: 'paths/specification-storage/specification-fields-path.yaml'
+  /specification-storage/fields/{id}:
+    $ref: 'paths/specification-storage/fields-by-id-path.yaml'

api/parameters/specificationId-param.yaml

@@ -0,0 +1,7 @@
+in: path
+name: specificationId
+description: Specification ID
+required: true
+schema:
+  type: string
+  format: uuid

api/paths/specification-storage/fields-by-id-path.yaml

@@ -0,0 +1,58 @@
+put:
+  summary: Update Field Definitions
+  description: Update a fields definition.
+  operationId: updateField
+  parameters:
+    - in: path
+      name: id
+      description: Specification Field ID
+      required: true
+      schema:
+        type: string
+        format: uuid
+  tags:
+    - specification-storage-fields
+  requestBody:
+    required: true
+    content:
+      application/json:
+        schema:
+          $ref: '../../schemas/specificationFieldChangeDto.yaml'
+        examples:
+          RequestExample:
+            $ref: '../../examples/request/specificationFieldChangeDto.yaml'
+  responses:
+    '202':
+      description: Field definition was updated
+      content:
+        application/json:
+          schema:
+            $ref: '../../schemas/specificationFieldDto.yaml'
+          examples:
+            RequestExample:
+              $ref: '../../examples/request/specificationFieldChangeDto.yaml'
+    '400':
+      $ref: '../../responses/badRequestResponse.yaml'
+    '500':
+      $ref: '../../responses/internalServerErrorResponse.yaml'
+delete:
+  summary: Delete Field Definition
+  description: Delete field definition
+  operationId: deleteField
+  parameters:
+    - in: path
+      name: id
+      description: Specification Field ID
+      required: true
+      schema:
+        type: string
+        format: uuid
+  tags:
+    - specification-storage-fields
+  responses:
+    '204':
+      description: Field definition was deleted
+    '400':
+      $ref: '../../responses/badRequestResponse.yaml'
+    '500':
+      $ref: '../../responses/internalServerErrorResponse.yaml'