Replace Service Description Profiles Enum with an open List #230

sebbader-sap · 2024-02-20T08:03:52Z

No description provided.

sebbader-sap · 2024-02-20T17:10:30Z

@danielporta I just tested it by manually translating it to JSON Schema. Summary: "oneOf" is wrong but "anyOf" does the job.

danielporta · 2024-02-26T13:58:21Z

@sebbader-sap: I don't think this will work. At least, the openapi-spec-validator did not succeed with my MWE.

openapi: 3.0.3
info:
  title: MWE for anyOf validation
  description: a description
  contact:
    name: Industrial Digital Twin Association (IDTA)
    email: info@idtwin.org
  license: 
    name: CC BY 4.0
    url: https://creativecommons.org/licenses/by/4.0/
  version: V3.0.1_SSP-001
paths:
  /description:
    get:
      tags:
        - Description API
      summary: Returns the self-describing information of a network resource (ServiceDescription)
      operationId: GetDescription
      x-semanticIds:
        - https://admin-shell.io/aas/API/Descriptor/GetDescription/3/0
      responses:
        '200':
          description: Requested Description
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceDescription'
components: 
  schemas:   
    ServiceDescription: 
      description: The Description object enables servers to present their capabilities to the clients, in particular which profiles they implement. At least one defined profile is required. Additional, proprietary attributes might be included. Nevertheless, the server must not expect that a regular client understands them.
      example: >-
        {
          "profiles": [
            "https://admin-shell.io/aas/API/3/0/AssetAdministrationShellRegistryServiceSpecification/SSP-002",
            "https://admin-shell.io/aas/API/3/0/SubmodelRegistryServiceSpecification/SSP-002"
          ]
        }
      properties: 
        profiles:
          type: array
          minItems: 1
          items:
            type: string
            anyOf:
              - const: "https://admin-shell.io/aas/API/3/0/AssetAdministrationShellServiceSpecification/SSP-001"
              - const: "https://admin-shell.io/aas/API/3/0/AssetAdministrationShellServiceSpecification/SSP-002"
              - const: "https://admin-shell.io/aas/API/3/0/SubmodelServiceSpecification/SSP-001"
              - const: "https://admin-shell.io/aas/API/3/0/SubmodelServiceSpecification/SSP-002"
              - const: "https://admin-shell.io/aas/API/3/0/SubmodelServiceSpecification/SSP-003"
              - const: "https://admin-shell.io/aas/API/3/0/AasxFileServerServiceSpecification/SSP-001"
              - const: "https://admin-shell.io/aas/API/3/0/AssetAdministrationShellRegistryServiceSpecification/SSP-001"
              - const: "https://admin-shell.io/aas/API/3/0/AssetAdministrationShellRegistryServiceSpecification/SSP-002"
              - const: "https://admin-shell.io/aas/API/3/0/SubmodelRegistryServiceSpecification/SSP-001"
              - const: "https://admin-shell.io/aas/API/3/0/SubmodelRegistryServiceSpecification/SSP-002"
              - const: "https://admin-shell.io/aas/API/3/0/DiscoveryServiceSpecification/SSP-001"
              - const: "https://admin-shell.io/aas/API/3/0/AssetAdministrationShellRepositoryServiceSpecification/SSP-001"
              - const: "https://admin-shell.io/aas/API/3/0/AssetAdministrationShellRepositoryServiceSpecification/SSP-002"
              - const: "https://admin-shell.io/aas/API/3/0/SubmodelRepositoryServiceSpecification/SSP-001"
              - const: "https://admin-shell.io/aas/API/3/0/SubmodelRepositoryServiceSpecification/SSP-002"
              - const: "https://admin-shell.io/aas/API/3/0/SubmodelRepositoryServiceSpecification/SSP-003"
              - const: "https://admin-shell.io/aas/API/3/0/SubmodelRepositoryServiceSpecification/SSP-004"
              - const: "https://admin-shell.io/aas/API/3/0/ConceptDescriptionServiceSpecification/SSP-001"
              - {}
      type: object

danielporta · 2024-02-26T14:05:09Z

Ah @sebbader-sap, I probably copied an old openapi version? 3.0.3 --> 3.1.0

sebbader-sap · 2024-02-26T14:38:38Z

Yep, you are right, "const" comes with OpenAPI V3.1.0, e.g.:

openapi: 3.1.0
info:
  title: MWE for anyOf validation
  description: a description
  contact:
    name: Industrial Digital Twin Association (IDTA)
    email: info@idtwin.org
  license: 
    name: CC BY 4.0
    url: https://creativecommons.org/licenses/by/4.0/
  version: V3.0.1_SSP-001
paths:
  /description:
    get:
      tags:
        - Description API
      summary: Returns the self-describing information of a network resource (ServiceDescription)
      operationId: GetDescription
      x-semanticIds:
        - https://admin-shell.io/aas/API/Descriptor/GetDescription/3/0
      responses:
        '200':
          description: Requested Description
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceDescription'
components: 
  schemas:   
    ServiceDescription: 
      description: The Description object enables servers to present their capabilities to the clients, in particular which profiles they implement. At least one defined profile is required. Additional, proprietary attributes might be included. Nevertheless, the server must not expect that a regular client understands them.
      example: >-
        {
          "profiles": [
            "https://admin-shell.io/aas/API/3/0/AssetAdministrationShellRegistryServiceSpecification/SSP-002",
            "https://admin-shell.io/aas/API/3/0/SubmodelRegistryServiceSpecification/SSP-002"
          ]
        }
      properties: 
        profiles:
          type: array
          minItems: 1
          items:
            type: string
            anyOf:
              - const: "https://admin-shell.io/aas/API/3/0/AssetAdministrationShellServiceSpecification/SSP-001"
              - const: "https://admin-shell.io/aas/API/3/0/AssetAdministrationShellServiceSpecification/SSP-002"
              - {}
      type: object

This one passes the validation.

sebbader-sap · 2024-02-26T14:39:08Z

I was also able to change the current state to a valid V3.0.3 version:

openapi: 3.0.3
info:
  title: MWE for anyOf validation
  description: a description
  contact:
    name: Industrial Digital Twin Association (IDTA)
    email: info@idtwin.org
  license: 
    name: CC BY 4.0
    url: https://creativecommons.org/licenses/by/4.0/
  version: V3.0.1_SSP-001
paths:
  /description:
    get:
      tags:
        - Description API
      summary: Returns the self-describing information of a network resource (ServiceDescription)
      operationId: GetDescription
      x-semanticIds:
        - https://admin-shell.io/aas/API/Descriptor/GetDescription/3/0
      responses:
        '200':
          description: Requested Description
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceDescription'
components: 
  schemas:   
    ServiceDescription: 
      description: The Description object enables servers to present their capabilities to the clients, in particular which profiles they implement. At least one defined profile is required. Additional, proprietary attributes might be included. Nevertheless, the server must not expect that a regular client understands them.
      example: >-
        {
          "profiles": [
            "https://admin-shell.io/aas/API/3/0/AssetAdministrationShellRegistryServiceSpecification/SSP-002",
            "https://admin-shell.io/aas/API/3/0/SubmodelRegistryServiceSpecification/SSP-002"
          ]
        }
      properties: 
        profiles:
          type: array
          minItems: 1
          items:
            type: string
            anyOf:
              - enum: 
                  - "https://admin-shell.io/aas/API/3/0/AssetAdministrationShellServiceSpecification/SSP-001"
              - enum: 
                  - "https://admin-shell.io/aas/API/3/0/AssetAdministrationShellServiceSpecification/SSP-002"
              
              - {}
      type: object

anyOf( enum1, enum2, ...) ... I don't know, doesn't look like a good solution to generate code from...

danielporta · 2024-02-27T10:15:04Z

As discussed in the meeting, we propose to change the OpenAPI definition to the following:

openapi: 3.1.0
info:
  title: DotAAS Part 2 | HTTP/REST | Asset Adminstration Shell Service Specification
  description: Description
  contact:
    name: Industrial Digital Twin Association (IDTA)
    email: info@idtwin.org
  license: 
    name: CC BY 4.0
    url: https://creativecommons.org/licenses/by/4.0/
  version: V3.0.1_SSP-001
paths:
  /description:
    get:
      tags:
        - Description API
      summary: Returns the self-describing information of a network resource (ServiceDescription)
      operationId: GetDescription
      x-semanticIds:
        - https://admin-shell.io/aas/API/Descriptor/GetDescription/3/0
      responses:
        '200':
          description: Requested Description
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceDescription'
components: 
  schemas:   
    ServiceDescription: 
      description: The Description object enables servers to present their capabilities to the clients, in particular which profiles they implement. At least one defined profile is required. Additional, proprietary attributes might be included. Nevertheless, the server must not expect that a regular client understands them.
      example: >-
        {
          "profiles": [
            "https://admin-shell.io/aas/API/3/1/AssetAdministrationShellRegistryServiceSpecification/SSP-002",
            "https://admin-shell.io/aas/API/3/0/SubmodelRegistryServiceSpecification/SSP-002"
          ]
        }
      properties: 
        profiles:
          type: array
          minItems: 1
          items:
            type: string
            minLength: 1
            maxLength: 2024
      type: object

sebbader-sap · 2024-02-28T17:14:07Z

@danielporta next attempt: Value of profiles is only type: string, however, I put all currently known profiles identifiers under example. Thereby, they are still in the file. My test with the openapi-validator tool did pass, also the rendering in Swaggerhub seems ok.

Part2-API-Schemas/openapi.yaml

BirgitBoss

Daniel checked my comments and answered by questions

* fix metadata and path endpoints * increase the version to the v3.0.2 bugfix version * remove bytes * remove "submodelElements" from SubmodelValue * Replace Service Description Profiles Enum with an open List (#230) * change servicedescription/profiles enum to an open list, providing predefined values only as examples * Remove Level from /$metadata (#250) * remove the Level modifier from $metadata requests * remove allOf SubmodelElementAttributes from SubmodelElementMetadata * fix ValueOnly description * PathItem Fix (#262) add array<pathitem> where missing + new pathitem regex * fix the regex pattern for part 2 classes according to the JSON schema regex (#256) * fix bugs in the valueonly classes * change annotations from array to value only * replace regex patterns with latest json schema v3.0.1 content * using the new string regex pattern also for part 2 classes --------- Co-authored-by: Alexander Gordt <100141498+alexgordtop@users.noreply.github.com>

change servicedescription/profiles enum to an open list

a6da4d6

sebbader-sap added bug Something isn't working breaking labels Feb 20, 2024

sebbader-sap added this to the 3.0.2 milestone Feb 20, 2024

sebbader-sap changed the base branch from main to IDTA-01002-3-0_bugfix-2-preparation February 20, 2024 09:06

sebbader-sap requested a review from danielporta February 20, 2024 09:10

fix: replace oneOf with anyOf for the open list of profiles

b87c2ae

remove anyOf, only providing values as examples

887973f

BirgitBoss reviewed Mar 4, 2024

View reviewed changes

Part2-API-Schemas/openapi.yaml Show resolved Hide resolved

danielporta approved these changes Mar 5, 2024

View reviewed changes

BirgitBoss approved these changes Mar 6, 2024

View reviewed changes

sebbader-sap merged commit 4244415 into IDTA-01002-3-0_bugfix-2-preparation Mar 12, 2024
1 check passed

sebbader-sap deleted the SeBa-replace-service-description-enum branch March 12, 2024 09:24

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Replace Service Description Profiles Enum with an open List #230

Replace Service Description Profiles Enum with an open List #230

sebbader-sap commented Feb 20, 2024

sebbader-sap commented Feb 20, 2024

danielporta commented Feb 26, 2024

danielporta commented Feb 26, 2024 •

edited

Loading

sebbader-sap commented Feb 26, 2024

sebbader-sap commented Feb 26, 2024 •

edited

Loading

danielporta commented Feb 27, 2024

sebbader-sap commented Feb 28, 2024

BirgitBoss left a comment

Replace Service Description Profiles Enum with an open List #230

Replace Service Description Profiles Enum with an open List #230

Conversation

sebbader-sap commented Feb 20, 2024

sebbader-sap commented Feb 20, 2024

danielporta commented Feb 26, 2024

danielporta commented Feb 26, 2024 • edited Loading

sebbader-sap commented Feb 26, 2024

sebbader-sap commented Feb 26, 2024 • edited Loading

danielporta commented Feb 27, 2024

sebbader-sap commented Feb 28, 2024

BirgitBoss left a comment

Choose a reason for hiding this comment

danielporta commented Feb 26, 2024 •

edited

Loading

sebbader-sap commented Feb 26, 2024 •

edited

Loading