AMF 5.7.2 Release Notes

This release introduces limited (phase 1) support for OpenAPI Specification (OAS) 3.1.

Our goal with this version is to support parsing/transforming/rendering OAS 3.1 APIs correctly, we achieved that goal with all the new fields and validations OAS 3.1 introduces, but we limit the support to just that. More info under Limitations title.

What's New: Limited OpenAPI 3.1 Support

Root Model

New webhooks field: We've added parsing and rendering support for the new webhooks field at root level (for callback mechanisms).
New jsonSchemaDialect field: We've added parsing and rendering support for the new jsonSchemaDialect field at root level.
- NOTE: While it's stored, its functionality (applying it as a default schema) is not yet implemented.
ComponentsObject - New PathItems field in Components: You can now define reusable PathItems objects within the components section, aligning with the new capabilities of OAS 3.1.

New Fields in OAS 3.1 objects

Several core OAS objects have been updated to support new fields and features introduced in OAS 3.1:

ReferenceObject - New summary and description Fields: $ref fields can now include summary and description fields.
DiscriminatorObject - Extensions Support: The discriminator object now correctly parses and stores extensions.
InfoObject - New summary Field: The root-level info object now supports the summary field.
LicenseObject - New identifier Field and Exclusive Fields Validation: The license has been updated with the new identifier field for SPDX license identifiers. Additionally, enhanced validations ensure that the identifier and url/name fields are used exclusively as per the OAS 3.1 specification.
SchemaObject - New $schema Field: The $schema field from OAS 3.1 is now parsed and stored within the SchemaObject.
- NOTE: Similar to jsonSchemaDialect, its functionality (applying it as a default schema) is not yet implemented.
SchemaObject - Removal of nullable Field: In alignment with OAS 3.1's move to JSON Schema Draft 2020-12 (where nullable is replaced by type: ['string', 'null'] for example), the nullable field has been removed from schemas.
SecurityScheme - New Security Scheme Type mutualTLS: AMF now recognizes and supports the new mutualTLS security scheme type introduced in OAS 3.1.

Validation Improvements & Changes

This release includes new validations that follow OAS 3.1 rules:

New Validation - Path Parameter Values: Path parameter values cannot contain the unescaped characters /, ? or #.
New Validation - Server Variable's enum and default Validations: if a Server Variable defines an enum facet (which is not required) it must define a non-empty array, and if the enum facet is defined the default value MUST be defined in the enum's values
Validation Change - OperationObject responses Field is Optional: The responses field within an operation is now considered optional
Validation Change - At least paths, components, or webhooks must be defined: A new validation rule ensures that an OpenAPI document defines at least one of paths, components, or webhooks at the top level.

Limitations

While AMF 5.7.2 offers foundational support for OAS 3.1, it's important to be aware of the following limitations in this release. These areas are currently out of scope for the limited OAS 3.1 implementation:

Conversions between Specs: The ability to convert an API definition from OAS 2.0 or 3.0 to OAS 3.1, or vice-versa, hasn't been fully tested thus is not supported. This release focuses solely on parsing/transforming/rendering OAS 3.1 APIs correctly.
OAS 3.1 Components Asset: Support for the new Components asset type in OAS 3.1 is out of scope.
JSON Schema 2020-12 Support:
- JSON Schema 2020-12 Semantics: The full functional adoption and application of JSON Schema Draft 2020-12 within the AMF model is out of scope. While some related fields are parsed (like $schema and jsonSchemaDialect), their semantic implications on schema validation or transformation within AMF are not active.
- jsonSchemaDialect Application: The jsonSchemaDialect field in the OpenAPIObject is parsed and stored, but AMF does not currently apply its declared dialect as a default schema for subsequent schemas in the document.
- $schema Application: Similarly, the $schema field within OAS 3.1 schemas is parsed and stored, but AMF does not apply its declared schema dialect for the individual schema.

Thank you.

Full OAS 3.1 API

This is a complete OAS 3.1 API showing the new fields and features we've added:

openapi: 3.1.0
info:
  title: OAS 3.1 with all new fields
  version: 1.0.0
  summary: summary of the API
  license:
    name: Apache 2.0
    identifier: Apache-2.0 # THIS IS NEW
jsonSchemaDialect: https://spec.openapis.org/oas/3.1/dialect/base # NEW OBJECT - not being applied
webhooks: # NEW OBJECT
  /newPet:
    post:
      requestBody:
        description: Information about a new pet in the system
        content:
          application/json:
            schema: { }
      responses:
        "200":
          description: Return a 200 status to indicate that the data was received successfully
  testWebhook: # webhooks don't need to start with '/' as pathItems
    $ref: '#/components/pathItems/testEndpoint'

paths:
  /users:
    post:
      operationId: getUsers
      responses:
        '200':
          description: this response description should override the referenced one
          $ref: '#/components/responses/usersListResponse'
      requestBody:
        description: this request description should override the referenced one
        $ref: '#/components/requestBodies/createUserRequest'

  /test:
    $ref: '#/components/pathItems/testEndpoint' # THIS IS NEW

security:
  - openIdConnect:
      - some
  - apikey:
      - something
      - other thing
  - http:
      - something else
  - mutualTLS:
      - other something

components:
  schemas:
    oneOfSchema:
      discriminator:
        x-custom-ann-test: custom ann value # THIS IS NEW
        x-custom-ann: custom ann value # THIS IS NEW
        propertyName: a
      oneOf:
        - type: object
          properties:
            a:
              type: string
        - type: object
          properties:
            b:
              type: string
    User:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        email:
          type: string
    OtherSchema:
      $schema: https://spec.openapis.org/oas/3.1/dialect/base # NEW OBJECT - not being applied
      type: object
      properties:
        some:
          type: string
    NullPropSchema:
      type: object
      properties:
        nullProp:
          type: null
    NullableSchema:
      anyOf: # THIS REPLACES NULLABLE
        - type: "string"
        - type: "null"

  responses:
    usersListResponse:
      description: this response description should be overridden
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: '#/components/schemas/User'
          examples:
            usersExample:
              summary: this example summary should override the referenced one # THIS IS NEW
              description: this example description should override the referenced one # THIS IS NEW
              $ref: '#/components/examples/usersList'

  requestBodies:
    createUserRequest:
      description: this request description should be overridden
      content:
        application/json:
          schema:
            type: string

  examples:
    usersList:
      summary: this example summary should be overridden
      description: this example description should be overridden
      value:
        - id: "1"
          name: Alice
          email: alice@example.com
        - id: "2"
          name: Bob
          email: bob@example.com

  securitySchemes:
    apikey:
      type: apiKey
      name: someApiKeyName
      in: header
    http:
      type: http
      scheme: bearer
      bearerFormat: JWT
    openIdConnect:
      type: openIdConnect
      description: openIdConnect security scheme
      openIdConnectUrl: https://a.ml/
    mutualTLS: # THIS IS NEW
      type: mutualTLS
      description: mutualTLS security scheme

  pathItems: # NEW OBJECT - not being applied
    testEndpoint: # doesn't need to start with '/' like pathItems
      get:
        responses:
          '200':
            description: A simple string response
            content:
              text/plain:
                schema:
                  type: string

What's Changed

W-10548354: server variables validations in OAS 3.1 by @arielmirra in #2111
W-10548360 - Added new MutualTLS security scheme for OAS 3.1 by @looseale in #2112
W-18215550: restrict which payloads FixFilePayloads applies to by @arielmirra in #2113
W-18217146: Publish 5.7.1 dev by @damianpedra in #2118
W-10548352 - $schema parsing in OAS 3.1 SchemaObject by @looseale in #2119
W-17778257: add warning for undefined path params in OAS by @arielmirra in #2120
W-10548356: remove nullable key from OAS 3.1 shapes by @arielmirra in #2121
W-18052245 - Fixed nested ref resolution to ExternalFragment with com… by @looseale in #2122
W-10548357: OAS 3.1 root nodes validations by @arielmirra in #2123
W-10548353 - Removed empty responses validation for OAS 3.1 by @looseale in #2124
W-10548234 - OAS 3.1 validation for path param names by @looseale in #2125
W-17846442: test DefaultNode serialization to sourcemaps by @arielmirra in #2127
W-18406612 - Fix in types specialization in JsonLdSchema parsing by @looseale in #2126
W-18395852: update ajv uri format to accept empty payloads by @arielmirra in #2128
W-18193252: stop emitting tuple shapes in OAS, add warning and violation by @arielmirra in #2129
W-16712362 - Adding OAS 3.1 plugin to OAS generic config by @looseale in #2130
W-18551455: add json-pointers support in ref nodes to external files by @arielmirra in #2131
W-16712375 - Fix in OAS2 plugin applies by @looseale in #2132
W-10548503: parse/emit 'pathItems' in OAS 3.1 components node by @arielmirra in #2133
W-18337812 - Disable Ajv console logger by @looseale in #2134
W-10548505: add missing OAS 3.1 typings by @arielmirra in #2135
W-18635564: update amf model to 3.11.0 by @arielmirra in #2136
W-18635564: update amf model to 3.11.0 for OAS 3.1 basic support by @arielmirra in #2137

Full Changelog: 5.7.1...5.7.2

Navigation Menu

5.7.2

Choose a tag to compare

Sorry, something went wrong.