ADP
API Design PrincipleBETA

English

繁體中文

English

繁體中文

Appearance

[ADP-761] OpenAPI: public shared schemas ​

Guidance ​

  • SHOULD publish stable schemas to a public site for reuse across projects/teams.
  • MUST use semantic versioning for published schemas as outlined in ADP-24.
  • SHOULD document all published schemas thoroughly, including descriptions for each field.
  • MUST ensure backward compatibility when updating published schemas, or increment the major version if breaking changes are necessary.

What Deserves to Be Published? ​

  • ProblemDetail Schema: Standardized schema for representing HTTP problem details.
  • ErrorResponse Schema: Common schema for API error responses.
  • ErrorResponseExample Schema: Example schemas for different error responses.
  • CloudEvent Schema: Schema for CloudEvents as defined by the CNCF.
  • Pagination Schema: Common schema for paginated responses.
  • SortOrder Schema: Schema for defining sort order in requests.
  • Filter Schema: Generic schema for filtering requests.
  • Object Schema:
    • These schemas change too frequently.
    • If you'd like to publish, use versioning to manage updates and ensure backward compatibility.

Benefits of Shared Schemas ​

  1. Consistency: Using shared schemas ensures that common data structures are uniform across different APIs.
  2. Maintainability: Centralized management of schemas simplifies updates and changes.
  3. Efficiency: Reduces duplication of effort in defining and documenting common structures.
  4. Interoperability: Promotes easier integration between different services and systems.

Implementation Details ​

Publishing Process ​

  1. Review and approve the schema within your team.
  2. Version the schema according to ADP-24.
  3. Publish the schema to a designated public repository or API registry.
  4. Update documentation to reflect the new or updated schema.

Referencing Published Schemas ​

When referencing a published schema, use the full URL to the specific version:

yaml
components:
  schemas:
    Error:
      $ref: 'https://api.example.com/schemas/v1/Error.yaml'

Examples ​

Problem Details (HTTP Problem) ​

yaml
ProblemDetails:
  type: object
  properties:
    type:
      type: string
      format: uri
    title:
      type: string
    status:
      type: integer
      format: int32
    detail:
      type: string
    instance:
      type: string
      format: uri
  required:
    - type
    - title
    - status
    - detail

CloudEvents ​

yaml
CloudEvent:
  type: object
  properties:
    specversion:
      type: string
      enum: ["1.0"]
    type:
      type: string
    source:
      type: string
      format: uri
    id:
      type: string
    time:
      type: string
      format: date-time
    datacontenttype:
      type: string
    data:
      type: object
  required:
    - specversion
    - type
    - source
    - id

Best Practices ​

  1. Keep schemas as simple and generic as possible to maximize reusability.
  2. Provide clear documentation for each schema, including usage examples.
  3. Establish a governance process for schema updates and versioning.
  4. Regularly review and update shared schemas based on feedback and evolving requirements.
  5. Consider creating language-specific bindings or code generation tools for popular programming languages.

References ​