Releases · aml-org/amf

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

...

Assets 2

01 Jul 21:39

BlockLucas

4.1.3

7a89caa

Changes in AMF 4.1.3

Released Jul 01, 2020.

JS asset

JVM asset

Validation Changes

OAS 30 recursive reference validation

fixed a bug in which an invalid recursive reference was not detected, for example, the following API is now invalid:

{
  "openapi": "3.0.0",
  "info": {
    "version": "0.0.1",
    "title": "test"
  },
  "paths": {
    "/path": {
      "post": {
        "responses": {
          "400": {
            "description": "desc",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/mytype"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "mytype": {
        "$ref": "#/components/schemas/mytype"
      }
    }
  }
}

RAML 1.0

Now, in RAML 1.0, if you didn't defined the field scopes in your OAuth 2.0 SecuritySchema definition you can use any scope in the implementation, for example, the following API is now valid:

#%RAML 1.0
title: GitHub API
securitySchemes:
  oauth_2_0:
    description: This API supports OAuth 2.0 for authenticating all API requests.
    type: OAuth 2.0
    settings:
      accessTokenUri:   https://someurl/oauth2/access_token
      authorizationGrants: [ client_credentials ]
/users:
  get:
    securedBy: [ oauth_2_0: { scopes: [ USER ] } ]

Async 2.0 (Beta)

Added validation for Query parameters and fragments used on Channels Object, for example, the following API is now invalid:

asyncapi: 2.0.0

info:
  title: Signup service example (internal)
  version: 0.1.0

channels:
  /user/signedup?foo=1:

Cross-spec validation

If you are using an internal interface (like RuntimeCompiler) & at the same time you were not specifying any Vendor (Like RAML10 or OAS20) when parsing, you will encounter a validation saying that it is invalid to have cross-spec APIs (e.g.: RAML 0.8 spec referencing RAML 1.0 DataType fragment)
This validation already existed in vendor-defined compilations.

Interface Changes

Added methods:

amf.client.model.domain.Callback.withEndpoint()
amf.client.model.domain.DialectDomainElement.getScalarValueByPropertyUri()
amf.client.model.domain.ParametrizedSecurityScheme.description()
amf.client.model.domain.ParametrizedSecurityScheme.withDescription()
amf.client.model.domain.NodeShape.withAdditionalPropertiesSchema()
amf.client.model.domain.Payload.encodings() (deprecates amf.client.model.domain.Payload.encoding())
amf.client.model.domain.Payload.withEncodings() (deprecates amf.client.model.domain.Payload.withEncoding())

Updated:

These interfaces were unusable before this release

Method amf.client.model.domain.Callback.withEndpoint() changed its signature
Method amf.client.model.domain.NodeShape.withPropertyNames() changed its return type from amf.plugins.domain.shapes.models.NodeShape to amf.client.model.domain.NodeShape

AMF Fixed issues

Assets 2

23 Jun 19:57

BlockLucas

4.1.2-1

8e27866

Changes in AMF 4.1.2-1

Released Jun 23, 2020.

JS asset

JVM asset

This Hotfix comes with an improvement in Error handling for CanonicalWebAPI transformations.
This change doesn't affect the standard webapi usage of the framework, either their interface or behavior.

AMF Fixed issues

APIMF-2138 - Exception while transforming to CanonicalWebAPI

Assets 2

23 Jun 19:56

BlockLucas

4.1.1-1

a9e2153

Changes in AMF 4.1.1-1

Released Jun 23, 2020.

JS asset

JVM asset

This Hotfix comes with improvements in Performance & Error handling for CanonicalWebAPI transformations.
These changes doesn't affect the standard webapi usage of the framework, either their interface or behavior.

AMF Fixed issues

Assets 2

11 Jun 21:04

BlockLucas

4.1.2-0

ad25085

Changes in AMF 4.1.2-0

Released Jun 11, 2020.

JS asset

JVM asset

OAS 30 Validation Changes

Status code in OAS 30 specs now must be a string as specified in spec.

This field MUST be enclosed in quotation marks (for example, "200") for compatibility between JSON and YAML.

See OpenAPI Specification here: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#patterned-fields-1

For example the following API is now invalid:

openapi: "3.0.0"
info:
  version: 1.0.0
  title: 1-api
paths:
  /test:
    get:
      responses:
        200: # quote this key to fix it
          description: 200 response

AMF Fixed issues

Assets 2

03 Jun 23:03

BlockLucas

4.1.2

bb929f6

Changes in AMF 4.1.2

Released Jun 03, 2020.

JS asset

JVM asset

Validation Changes

OAS YAML references

Fixed an invalid validation on references to YAML files for OpenAPI specs, for example, the following API is now valid:

api.yaml:

swagger: '2.0'
info:
  title: Sample API
  version: ''
paths:
  /resource:
    get:
      responses:
        '200':
          description: ''
          schema:
            $ref: 'f/complexType.yaml'
  /resource2:
    get:
      responses:
        '200':
          description: ''
          schema:
            $ref: 'f/baseType.yaml'

f/complexType.yaml:

type: object
properties:
  ref:
    $ref: baseType.yaml

f/baseType.yaml:

type: object
properties:
  name:
    type: string

Duplicate keys

Fixed a bug where duplicate keys with one being in quotation marks were not being validated, for example, the following API is now invalid:

#%RAML 1.0
title: A title

types:
  SomeType:
    type: object
    properties:
      type: boolean
      "type":
          type: string

OAS Emission change

A performance improvement was made with regards to OAS emission. Declared types which are used multiple time throughout a specification are now only rendered once and then referenced when used. Here is a simple example of converting to from raml to oas.

#%RAML 1.0
title: compact emission test
types:
  Person:
    properties:
      name: string
/invoices:
  get:
    responses:
      200:
        body:
          properties:
            a: Person
            b: Person

swagger: "2.0"
info:
  title: compact emission test
  version: "1.0"
paths:
  /invoices:
    get:
      responses:
        "200":
          description: ""
          schema:
            type: object
            required: [a, b]
            properties:
              a:
                $ref: "#/definitions/Person"
              b:
                $ref: "#/definitions/Person"
definitions:
  Person:
    type: object
    required:
      - name
    properties:
      name:
        type: string

AMF Fixed issues

Assets 2

08 May 15:35

BlockLucas

4.1.1

79e253e

Changes in AMF 4.1.1

Released May 08, 2020.

JS asset

JVM asset

Interface changes

ExecutionEnvironment

Dialect registration interfaces were fixed to receive a scheduler inside the environment, instead of outside

BaseUnit

Added the posibility to set the model Id

amf.client.model.document.BaseUnit.withId() (with descendants)

Updated JS typings

Updated typings for:

Dialect
DialectInstance
DialectDomainElement
NodeMapping
PropertyMapping

Updated JS Client Interface

Added missing UnionNodeMapping

model.domain.UnionNodeMapping.this()
model.domain.UnionNodeMapping.name()
model.domain.UnionNodeMapping.withName()

Parse behavior normalization

Person
  type: AnotherPerson[]

Person:
  type: array
  items: AnotherPerson

Are resolved in the same way now in Parse stage (before, case A were resolved in Resolve stage)

Validation Changes

Fixed behaviour with Recursive Shapes, for example the following API is now valid:

{
  "swagger": "2.0",
  "info": {
    "title": "test",
    "version": "1.1"
  },
  "definitions": {
    "Causes": {
      "$ref": "#/definitions/Test"
    },
    "Test": {
      "properties": {
        "subsenses": {
          "items": {
            "$ref": "#/definitions/Test"
          },
          "minItems": 1,
          "type": "array"
        }
      },
      "type": "object"
    }
  },
  "paths": {}
}

And the next one invalid:

#%RAML 1.0
title: Recursive
types:
  Recursive:
    type: object
    properties:
      myP:
        type: Recursive
/recursiveType:
  post:
    responses:
      201:
        body:
          application/json:
            type: Recursive

AMF Fixed issues

Assets 2

16 Apr 21:04

BlockLucas

4.1.0

b9e2253

Changes in AMF 4.1.0

Released Apr 16, 2020.

JS asset

JVM asset

Interface Changes

Thread Management (JAVA only)

This version allows creating an "ExecutionEnvironment" using a Java ScheduledExecutorService. The internal AMF threads are created in the thread pool provided by that scheduler instead of the global thread pool provided by Scala. This enables implementers to handle the pool size & other tunings on their own.
The following interfaces can now receive this:

amf.client.AMF.init()
amf.client.AMF.platform()
amf.client.AMF.registerDialect()
amf.client.environment.Environment.executionEnvironment()
amf.Core.generator()
amf.Core.init()
amf.Core.parser()
amf.plugins.document.Vocabularies.registerDialect()
amf.plugins.document.WebApi.register()
amf.plugins.features.validation.SHACLValidator.report()
amf.plugins.features.validation.SHACLValidator.validate()
AnyShape.buildJsonSchema()
AnyShape.buildRamlDatatype()
AnyShape.parameterValidator()
AnyShape.payloadValidator()
AnyShape.toJsonSchema()
AnyShape.toRamlDatatype()
AnyShape.validate()
AnyShape.validateParameter()

In order to build it, you have to use an "ScheduledExecutorService" in

amf.client.execution.ExecutionEnvironment()

OperationModel

operationId was added to OperationModel

amf.client.model.domain.Operation.operationId()
amf.client.model.domain.Operation.withOperationId()

Validation Changes

OAS Validation with references

OAS references to external YAML files is now supported.
For example, the following api definition will now be valid:

root.yaml

swagger: "2.0"
info:
  version: 1.0.0
  title: Swagger Petstore
paths:
  /pets:
    get:
      responses:
        "200":
          description: unexpected error
          schema:
            $ref: 'ref.yaml'

ref.yaml

type: object
required:
  - code
  - message
properties:
  code:
    type: integer
    format: int32
  message:
    type: string

AMF Fixed issues

Assets 2

13 Mar 22:32

BlockLucas

4.0.6

02f9958

Changes in 4.0.6

Released Mar 13, 2020.

JS asset

JVM asset

Interface Changes

Changed bindings

New intermediate object was created to enable named bindings.

amf.client.model.domain.EndPoint.bindings changed its return type to amf.client.model.domain.ChannelBindings
amf.client.model.domain.Operation.bindings changed its return type to amf.client.model.domain.OperationBindings
amf.client.model.domain.Request.bindings changed its return type to amf.client.model.domain.MessageBindings
amf.client.model.domain.Response.bindings changed its return type to amf.client.model.domain.MessageBindings
amf.client.model.domain.Server.bindings changed its return type to amf.client.model.domain.ServerBindings

Example:

Before

val bindingsList List[ServerBinding] = EndPoint.bindings()

Now

val bindingsObject ChannelBindings  = EndPoint.bindings()
val bindingList List[ServerBinding] = bindingsObject.bindings()

This applies exactly the same with the interfaces mentioned before.

New bindings methods

amf.client.model.domain.EndPoint.withBindings (added)
amf.client.model.domain.Operation.withBindings (added)
amf.client.model.domain.Request.withBindings (added)
amf.client.model.domain.Response.withBindings (added)
amf.client.model.domain.Server.withBindings (added)

New validate method for payloads

If you are currently blocking the asynchronous payload validation call you can use the following new method:

amf.client.validate.PayloadValidator.syncValidate (synchronous)

OAS 2.0 Validation changes

Body parameters.

Duplicated body parameters are now being validated.
For example, the following api definition will now be invalid:

{
    "swagger": "2.0",
    "info": {
        "title": "Test",
        "version": "1.0.0"
    },
    "paths": {
        "/": {
            "parameters": [
                {
                    "name": "body parameter 1",
                    "in": "body",
                    "schema": {}
                },
                {
                    "name": "body parameter 2",
                    "in": "body",
                    "schema": {}
                }
            ],
            "get": {
                "responses": {
                    "200": {
                        "description": "ok"
                    }
                }
            }
        }
    }
}

Security requirement object

Security requirement object value is now being correctly validated as an array.

Valid example:

{
  "swagger" : "2.0",
  "info" : {
    "title" : "Registry",
    "version" : "1"
  },
  "paths" : {
  },
  "security" : [ {
    "Bearer" : []
  } ],
  "securityDefinitions" : {
    "Bearer" : {
      "in" : "header",
      "name" : "Authorization",
      "type" : "apiKey"
    }
  }
}

Invalid example:

{
  "swagger" : "2.0",
  "info" : {
    "title" : "Registry",
    "version" : "2"
  },
  "paths" : {
  },
  "security" : [ {
    "Bearer" : ""
  } ],
  "securityDefinitions" : {
    "Bearer" : {
      "in" : "header",
      "name" : "Authorization",
      "type" : "apiKey"
    }
  }
}

Info Object

Required facet "name" is now being validated.

Valid example:

{
    "swagger": "2.0",
    "info": {
        "title": "Testing API",
        "version": "1.0.0",
        "name": "my name",
        "license": {}
    },
    "paths": {}
}

Invalid example:

{
    "swagger": "2.0",
    "info": {
        "title": "Testing API",
        "version": "1.0.0",
        "license": {}
    },
    "paths": {}
}

AMF Fixed issues

Assets 2

13 Feb 18:35

BlockLucas

4.0.5

e229fde

Changes in 4.0.5

Released Feb 13, 2020.

JS asset

JVM asset

Interface Changes

Async 2.0 Objects

New objects for Async 2.0 (beta)

amf.client.parse.Async20Parser

Compact json schema emission

When building a json schema from a shape (descendants of amf.client.model.domain.AnyShape), a new parsing option has been added to provide an alternative compacted emission. This extracts common types that are used throughout the resulting schema, and emits these schemas in the definitions facet.

shape.buildJsonSchema(ShapeRenderOptions().withCompactedEmission)

Validation changes

Improved validation of required facet in JSON schemas.

In JSON Schema 3 required facet is a boolean.
From JSON Schemas 4 & newer versions, it is an array (4 is used if no version is specified).

For example, the following schema definition will now be invalid:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "id": "id",
      "type": "string",
      "required": "true"
    }
  }
}

OAS 20 type parameter

Missing "type" facet in parameters are now validated, the following example is now invalid:

"parameters": [
          {
            "in": "query",
            "name": "filename",
            "required": true
          }
        ]

JSON Schema Properties

JSON Schema properties definitions are now validated, the following example that contains an array instead of an object for property definitions (usually a mistake using examples in the definitions) is now invalid:

{
  "$schema": "http://json-schema.org/schema",
  "type": "object",
  "properties": [
    {
      "date": "2019-10-21 13:31:17"
    },
    {
      "amount": "-13.00"
    }
  ]
}

Any JSON Schemas

JSON schemas with no types definition will now be validated correctly, for example the following raml is now valid:

types:
  Client:
    type: |
      {
        "$schema": "http://json-schema.org/draft-03/schema",
        "type": "object",
        "properties": {
          "from": {
            "required": true
          }
        }
      }
    example:
      {
        "from": "test"
      }

Before an Object was expected for the "from" value

AMF Fixed issues

Assets 2

Releases: aml-org/amf

Changes in AMF 4.2.0

Custom Validations Expanded ("New feature!")

What's new?

SPARQL and extended SHACL functions

JS functions are not supported anymore

More performance in JVM

Dynamic model property names

Validation Changes

Cyclic References in OAS APIs

YAML References fix

RAML Overlay example validation

AsyncAPI 2.0 (still beta) & OAS 3.0

AML Validation

Interface Changes

Added methods:

Updated:

AML Vocabularies and Canonical Web Api Dialect Repository Migration

Canonical Web API Spec Transformation Repository Migration

Changes in AMF 4.1.3

Validation Changes

OAS 30 recursive reference validation

RAML 1.0

Async 2.0 (Beta)

Cross-spec validation

Interface Changes

Added methods:

Updated:

AMF Fixed issues

Changes in AMF 4.1.2-1

AMF Fixed issues

Changes in AMF 4.1.1-1

AMF Fixed issues

Changes in AMF 4.1.2-0

OAS 30 Validation Changes

AMF Fixed issues

Changes in AMF 4.1.2

Validation Changes

OAS YAML references

Duplicate keys

OAS Emission change

AMF Fixed issues

Changes in AMF 4.1.1

Interface changes

ExecutionEnvironment

BaseUnit

Updated JS typings

Updated JS Client Interface

Parse behavior normalization

Validation Changes

AMF Fixed issues

Changes in AMF 4.1.0

Interface Changes

Thread Management (JAVA only)

OperationModel

Validation Changes

OAS Validation with references

AMF Fixed issues

Changes in 4.0.6

Interface Changes

Changed bindings

New bindings methods

New validate method for payloads

OAS 2.0 Validation changes

Body parameters.

Security requirement object

Info Object

AMF Fixed issues

Changes in 4.0.5

Interface Changes

Async 2.0 Objects

Compact json schema emission

Validation changes

Improved validation of required facet in JSON schemas.

OAS 20 type parameter

JSON Schema Properties

Any JSON Schemas

AMF Fixed issues