Skip to content

Changes in AMF 4.2.0
Compare
Choose a tag to compare
@looseale looseale released this 30 Jul 21:32
· 3204 commits to master since this release
4.2.0
95e4bfa
This commit was created on GitHub.com and signed with GitHub’s verified signature. The key has expired.
GPG key ID: 4AEE18F83AFDEB23
Expired
Learn about vigilant mode.

Released Jul 30, 2020.

JS asset

JVM asset

Custom Validations Expanded ("New feature!")

What's new?

Custom Validations now left beta support! This come with some changes.

SPARQL and extended SHACL functions

Now you can use SPARQL in your custom validations and some new SHACL functions.
You can find more information and examples in Validation Tutorial.

JS functions are not supported anymore

With the addition of SPARQL there is no need of using JS functions.

More performance in JVM

SHACL is now consumed directly from Apache Jena in JVM instead of using Nashorn to consume the SHACL JS library.

Dynamic model property names

We changed the way that properties are named in our dynamic model (DataNode): previously the properties were named with an autogenerated name ("scalar_#", "object_#", etc.), now they take the name of the parent node. These autogenerated names are not being used by implementors.
For reference, with this example:

openapi: 3.0.0
info:
  title: Sample API
  version: undefined
components:
  schemas:
    person:
      properties:
        name:
          type: string
        age:
          type: integer
      example:
        name: John Doe
        age: 44
paths: {}

This was the JSON-LD representation of the example previously:

"apiContract:examples": [
  {
    "@id": "#2",
    "@type": [
      "apiContract:Example",
      "doc:DomainElement"
    ],
    "doc:strict": [
      {
        "@value": true
      }
    ],
    "doc:structuredValue": [
      {
        "@id": "#3",
        "@type": [
          "data:Object",
          "data:Node",
          "doc:DomainElement"
        ],
        "data:name": [
          {
            "@id": "#4",
            "@type": [
              "data:Scalar",
              "data:Node",
              "doc:DomainElement"
            ],
            "data:value": [
              {
                "@value": "John Doe"
              }
            ],
            "shacl:datatype": [
              {
                "@id": "http://www.w3.org/2001/XMLSchema#string"
              }
            ],
            "core:name": [
              {
                "@value": "scalar_2"
              }
            ]
          }
        ],
        "data:age": [
          {
            "@id": "#5",
            "@type": [
              "data:Scalar",
              "data:Node",
              "doc:DomainElement"
            ],
            "data:value": [
              {
                "@value": "44"
              }
            ],
            "shacl:datatype": [
              {
                "@id": "http://www.w3.org/2001/XMLSchema#integer"
              }
            ],
            "core:name": [
              {
                "@value": "scalar_3"
              }
            ]
          }
        ],
        "core:name": [
          {
            "@value": "object_1"
          }
        ]
      }
    ],
    "doc:raw": [
      {
        "@value": "name: John Doe\nage: 44"
      }
    ]
  }
]

and this is the new one:

"apiContract:examples": [
  {
    "@id": "#2",
    "@type": [
      "apiContract:Example",
      "doc:DomainElement"
    ],
    "doc:strict": [
      {
        "@value": true
      }
    ],
    "doc:structuredValue": [
      {
        "@id": "#3",
        "@type": [
          "data:Object",
          "data:Node",
          "doc:DomainElement"
        ],
        "data:name": [
          {
            "@id": "#4",
            "@type": [
              "data:Scalar",
              "data:Node",
              "doc:DomainElement"
            ],
            "data:value": [
              {
                "@value": "John Doe"
              }
            ],
            "shacl:datatype": [
              {
                "@id": "http://www.w3.org/2001/XMLSchema#string"
              }
            ],
            "core:name": [
              {
                "@value": "name"
              }
            ]
          }
        ],
        "data:age": [
          {
            "@id": "#5",
            "@type": [
              "data:Scalar",
              "data:Node",
              "doc:DomainElement"
            ],
            "data:value": [
              {
                "@value": "44"
              }
            ],
            "shacl:datatype": [
              {
                "@id": "http://www.w3.org/2001/XMLSchema#integer"
              }
            ],
            "core:name": [
              {
                "@value": "age"
              }
            ]
          }
        ],
        "core:name": [
          {
            "@value": "object_1"
          }
        ]
      }
    ],
    "doc:raw": [
      {
        "@value": "name: John Doe\nage: 44"
      }
    ]
  }
]

Validation Changes

Cyclic References in OAS APIs

Cyclic references between files is now supported for OAS APIs. The example below shows an API that was invalid before but is valid now.

api.yaml

swagger: '2.0'
info:
  title: pet api
  version: 1.0
definitions:
  pet:
    type: object
    properties:
      animalRef:
        $ref: 'ref.yaml#/definitions/animal'
paths: {}

ref.yaml

definitions:
  animal:
    type: object
    properties:
      petRef:
        $ref: 'api.yaml#/definitions/pet'

YAML References fix

Fixed an Unresolved Reference bug with yaml references, for example, the following API is now valid:

api.yaml

swagger: "2.0"
info:
  title: 'test'
  version: "1.2"

paths:
  /pets:
    get:
      produces:
      - application/json
      responses:
        '403':
          $ref: 'ref.yaml#/responses/response1'

ref.yaml

definitions:
  TestSchema:
    type: string

responses:
  response1:
    description: 'test'
    schema:
      $ref: '#/definitions/TestSchema'

RAML Overlay example validation

Fixed an invalid validation with an example inside an Overlay, for example the following API is now valid:

api.raml

#%RAML 1.0
title: Test

types:
  TestEntity:
    type: object
    properties:
      id: string

overlay.raml

#%RAML 1.0 Overlay
title: Overlay
extends: ./api.raml

types:
  TestEntity:
    example: |
      {
        "id": "t123"
      }

AsyncAPI 2.0 (still beta) & OAS 3.0

Validation of invalid yaml tags was introduced as specified https://github.com/asyncapi/asyncapi/blob/master/versions/2.0.0/asyncapi.md#format
https://swagger.io/specification/

The following APIs are now invalid:

asyncapi: 2.0.0
info:
  title: Signup service example (internal)
  version: !!invalidTag 0.1.0
channels:
  /user/signedup:
    subscribe:
      message:
        payload:
          type: object
          properties:
            email:
              type: string
              format: email
openapi: 3.0.0
info:
  title: test
  version: !!invalidTag 0.1.0

paths:
  /pets:
    get:
      responses:
        '403':
          description: sd

AML Validation

  • Added a validation for duplicated terms, for example, the following example is now invalid as Term1 is used for classTerms & propertyTerms:
#%Vocabulary 1.0
vocabulary: Term
base: http://a.ml/vocabularies#
classTerms:
  Term1:
    displayName: Term1
    description: Term1 class
    properties:
      - Term1
propertyTerms:
    Term1:
      displayName: Term1
      description: Term1 property
      range: string
  • Reduced severity for missing class term validations from Violation to Warning. Now AML will not block using semantics defined outside of the vocabulary and not specified in externals
#%Vocabulary 1.0
vocabulary: Term
base: http://a.ml/vocabularies#
classTerms:
  MyClass:
    displayName: MyClass
    description: My class
    properties:
      - myProperty
propertyTerms:
    myProperty:
      displayName: myProperty
      description: My property
      range: InexistentClass # this will show now a warning since InexistentClass is not defined in classTerms

Interface Changes

Added methods:

  • amf.client.model.document.BaseUnit.withReferenceAlias()
  • amf.plugins.features.validation.SHACLValidator.supportsJSFunctions()
  • amf.client.model.domain.NodeMapping.isLink()
  • amf.client.model.domain.NodeMapping.linkLabel()
  • amf.client.model.domain.NodeMapping.withLinkTarget()
  • amf.client.model.domain.NodeMapping.withLinkLabel()
  • amf.client.model.domain.NodeMapping.linkTarget()
  • amf.client.model.domain.NodeMapping.linkCopy()
  • amf.client.model.domain.NodeMapping.link()

Updated:

These interfaces were unusable before this release

  • amf.plugins.features.validation.SHACLValidator.loadLibrary()

AML Vocabularies and Canonical Web Api Dialect Repository Migration

AML Vocabularies that were previously locates in the vocabulary/vocabulary folder have been migrated to the aml-org/amf-metadata repository. Canonical Web Api spec dialect has also been migrated.

The Validations Profile dialect (validations.raml) was moved to the documentation section.
The OAS 2.0 dialect was stale and was deleted.

You can find more information into how to use these assets in the aml-org/amf-metadata README.

Canonical Web API Spec Transformation Repository Migration

The CanonicalWebAPISpecTransformation was migrated to the aml-org/amf-metadata repository.

AMF Fixed issues

Assets 2
Loading