[ADP-762] OpenAPI: HTTP Profile basis

Guidance

• SHOULD use OpenAPI schema as HTTP Profile basis
• MUST follow ADP-758: OpenAPI $ref when referencing components
• SHOULD use ADP-756: OpenAPI Provide Examples to illustrate profile usage
• MUST adhere to ADP-24: Versioning Mechanism when updating schemas

Combining Profiles with OpenAPI Schema

Profiles can be combined with OpenAPI Schema to provide enriched semantics and constraints. OpenAPI Schema is primarily used to describe the structure and validation rules of an API, while profiles can offer additional semantics and conventions.

1. Define Profile

   • Define a profile that describes additional semantics and constraints for a specific resource.
   • Example:
     • Profile URI: http://example.com/profiles/user-profile
     • Description: This profile defines additional semantics for user resources, including validation rules and business constraints.

2. Reference Profile in OpenAPI Schema

   • Use the Link header or _links field to link profiles in the resource representation.
   • Example OpenAPI Schema referencing a profile:

openapi: 3.1.0
info:
  title: User API
  version: 1.0.0
paths:
  /users:
    get:
      summary: Get a list of users
      responses:
        '200':
          description: A list of users
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
              examples:
                example1:
                  value:
                    - name: John Doe
                      email: john.doe@example.com
                      _links:
                        profile:
                          href: "http://example.com/profiles/user-profile"
components:
  schemas:
    User:
      type: object
      properties:
        name:
          type: string
        email:
          type: string
          format: email
        _links:
          type: object
          properties:
            profile:
              type: object
              properties:
                href:
                  type: string
                  format: uri
                  example: "http://example.com/profiles/user-profile"

Related ADPs

• ADP-24: Versioning Mechanism
• ADP-756: OpenAPI Provide Examples
• ADP-758: OpenAPI $ref
• ADP-701: Property Design

References

• OpenAPI Specification
• JSON Hyper-Schema
• RFC 6906: The 'profile' Link Relation Type