Card API Level Specification Conventions

To streamline efforts and ensure maintainability we use a single source of Card API Specification file containing all information (src/CardInfoAPI.yaml) and build different specification files for level 1 and 2 on root serving as a implementation refernce. To achive a smooth handling, 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 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 endpoint by SFTI and relevant inforamtion are required to achive standarized information exchange. Optional information can still transferred optional.

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 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 mainainability 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
      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, and 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 schmeas only.

Our convention:

• optional porperties 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

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

DO NOT ADAPT FOR OAS

Invalid Example

DontDo:
  type: object
  properties:
    prop1:
      required: true   # invalid OAS syntax
      $ref: ./Prop1.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 bothe files do not contain x-api-level / x-required extension markers