Card API Level Specification Conventions

To streamline efforts and ensure maintainability we use a single source of the Card API Specification file containing all information (src/CardInfoAPI.yaml). From this file different specification files are built for level 1 and 2 (under the root folder) which are the relevant specifications for the users of the standard. To enable this approach, we introduce the OpenAPI extensions x-api-level and x-required in our source specification files (all files in src/**). This page explains how contributors should use these extensions.

TL;DR Summary

• Use x-api-level: 2 on tag, endpoint or parameter nodes to mean "Level 2 only (removed from Level 1)".
• Use x-required: 2 on object properties to mean "optional in Level 1, required in Level 2".
• Prefer keeping properties present in all levels and use x-required: 2 over removing them entirely with x-api-level, unless removal is truly required.

Overview

We generate two bundled OpenAPI specification variants from one generic file at src/CardInfoAPI.yaml:

• Level 1 | /CardInfoAPI-level1.yaml: Card API with basic information, reduces set of endpoints and many schemas are optional.
• Level 2 | /CardInfoAPI-level2.yaml: Card API with all specified endpoints by SFTI and more required properties/attributes to achieve standardized information exchange. Optional information can still be transferred optionally.

We achieve this with:
x-api-level → visibility control (include/exclude depending on target level)
x-required → requiredness control (optional in Level 1, required in Level 2) After bundling, we also strip these markers so final specs are clean.

x-api-level Extension (Filtering)

What it means
x-api-level indicates that a node is intended for a certain API level. No extension means the node is present in all level (default case).

Warning

Altough the x-api-level extension could be used on any node to filter out specific nodes, we encourage you to use this extension only on tag, endpoint and (request) parameter level. Do not use x-api-level on schema level to ensure compliance of the card level structure approach.

Our convention:

• Nodes without x-api-level are available in all levels. This has the same effect as x-api-level: 1 but for maintainability reasons we prefer using the implicit default case.
• Nodes with x-api-level: 2 are Level 2 only.
• Due to the card level structure approach there is no support for using nodes in Level 1 but filter them for Level 2.

Example

paths:
  /endpoint:
    get:
      ...
      parameters:
        - in: query
          name: query_parameter
          type: string
          ...
        - in: query
          name: level2_query_parameter
          x-api-level: 2
          type: string
          ...
  /level2-endpoint:
    get:
      ...
      x-api-level: 2
      tags:
        - xxx
      parameters:
        - in: query
          name: new_query_parameter
          type: string
          ...
        - in: query
          name: level2_new_query_parameter
          x-api-level: 2 # not needed here since this endpoint is only available in level 2
          type: string
          ...

Effect

• Level 1: the level2-endpoint endpoint is removed entirely, in /endpoint only the level2_query_parameter parameter is removed.
• Level 2: both endpoint with 2 parameters each is preserved.
• x-api-level is stripped from the final specification.

Result CardInfoAPI-level1.yaml

# CardInfoAPI-level1.yaml
paths:
  /endpoint:
    get:
      ...
      parameters:
        - in: query
          name: query_parameter
          type: string
          ...

Result CardInfoAPI-level2.yaml

# CardInfoAPI-level2.yaml
paths:
  /endpoint:
    get:
      ...
      parameters:
        - in: query
          name: query_parameter
          type: string
          ...
        - in: query
          name: level2_query_parameter
          type: string
          ...
  /level2-endpoint:
    get:
      ...
      parameters:
        - in: query
          name: new_query_parameter
          type: string
          ...
        - in: query
          name: level2_new_query_parameter
          type: string
          ...

x-required Extension (Level-specific Requiredness in Schemas)

What it means
The x-required extension is used to express: "This property is optional in Level 1, but required in Level 2."

Warning

Use the x-required extension for schemas only.

Our convention:

• optional properties in all levels should not use the x-required extension at all.
• required properties for all levels utilize the required field specified by the OAS standard.
• properties with x-required: 2 are added to the required field in the bundling process for Level 2 (only required for Level 2, Level 1 optional).
• x-required: 1is reserved for later use cases (Level 1 required and Level 2 optional) and should not be used now.

Example

CardDetails:
  type: object
  required:
    - card_id
  properties:
    card_id:
      $ref: ./CardId.yaml
    person_id:
      x-required: 2
      $ref: ./PersonId.yaml
    initial_issuing_date:
      $ref: ./InitialIssuingDate.yaml

Effect

• card_idis required for both levels
• initial_issuing_date is optional for both levels
• person_id is optional in Level 1, but required in Level 2
• x-required is stripped from the final specification.

Result CardInfoAPI-level1.yaml

# CardInfoAPI-level1.yaml
CardDetails:
  type: object
  required:
    - card_id
  properties:
    card_id:
      $ref: ./CardId.yaml
    person_id:
      $ref: ./PersonId.yaml
    initial_issuing_date:
      $ref: ./InitialIssuingDate.yaml

Result CardInfoAPI-level2.yaml

# CardInfoAPI-level2.yaml
CardDetails:
  type: object
  required:
    - card_id
    - person_id
  properties:
    card_id:
      $ref: ./CardId.yaml
    person_id:
      $ref: ./PersonId.yaml
    initial_issuing_date:
      $ref: ./InitialIssuingDate.yaml

Review

To validate your changes, please create a pull request, a pull request draft or run the bundle worflow on your branch. Review

• Check /cardIinfoAPI-level1.yaml to ensure Level 2 nodes are removed.
• Check /cardIinfoAPI-level2.yaml to contain all nodes and added required properties for x-required: 2.
• Ensure both files do not contain x-api-level / x-required extension markers