Skip to content

Releases: aml-org/amf

Changes in 4.3.0

27 Aug 20:26
@BlockLucas BlockLucas
4.3.0
caa8c64
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.
Compare
Choose a tag to compare
Changes in 4.3.0

Released Aug 27, 2020.

JS asset

JVM asset

SYAML

We bumped the version of SYAML dependency to 1.0.282, which contains some improvements that make us bump a minor. see details here https://github.com/mulesoft/syaml/releases/tag/1.0.281

Validation Changes

YAML multidocument

Added validation for a multi-document tag in YAML documents, for example, the following API is now invalid because the usage of "---":

api.raml:

#%RAML 1.0
title: api
---
/test:

RAML Security Schemes Fragments

APIMF-2261 - Missing validation in "scopes" parameter when applying a SecurityScheme fragment
Fixed a bug in which a Security Schemes wasn't properly validated if it was defined in a Typed Fragment, for example, the following API is now invalid, as it has an invalid scope definition

api.raml:

#%RAML 1.0
title: API

securitySchemes:
  oauth_2_0: !include /securitySchemes/oauth_2_0.raml

/users:
  get:
    securedBy: [ oauth_2_0: { scopes: [ USER ] } ]

/securitySchemes/oauth_2_0.raml:

#%RAML 1.0 SecurityScheme
description: |
  This API supports OAuth 2.0 for authenticating all API requests.
type: OAuth 2.0
settings:
  accessTokenUri:   https:/host/path/oauth2/access_token
  authorizationGrants: [ client_credentials ]
  scopes: [ ADMIN ]

AMF Fixed issues

Assets 2
Loading

Changes in 4.2.0-0

13 Aug 17:37
@AgustinBettati AgustinBettati
4.2.0-0
75a2917
Compare
Choose a tag to compare
Changes in 4.2.0-0

Released Aug 13, 2020.

JS asset

JVM asset

This is a hotfix for 4.2.0 that fixes an invalid validation for implicit tags in YAML.

AMF Fixed issues

Assets 2
Loading

Changes in AMF 4.2.0

30 Jul 21:32
@looseale looseale
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.
Compare
Choose a tag to compare
Changes in AMF 4.2.0

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

...

Read more
Assets 2
Loading

Changes in AMF 4.1.3

01 Jul 21:39
@BlockLucas BlockLucas
4.1.3
7a89caa
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.
Compare
Choose a tag to compare
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
Loading

Changes in AMF 4.1.2-1

23 Jun 19:57
@BlockLucas BlockLucas
4.1.2-1
8e27866
Compare
Choose a tag to compare
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

Assets 2
Loading

Changes in AMF 4.1.1-1

23 Jun 19:56
@BlockLucas BlockLucas
4.1.1-1
a9e2153
Compare
Choose a tag to compare
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
Loading

Changes in AMF 4.1.2-0

11 Jun 21:04
@BlockLucas BlockLucas
4.1.2-0
ad25085
Compare
Choose a tag to compare
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
Loading

Changes in AMF 4.1.2

03 Jun 23:03
@BlockLucas BlockLucas
4.1.2
bb929f6
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.
Compare
Choose a tag to compare
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
Loading

Changes in AMF 4.1.1

08 May 15:35
@BlockLucas BlockLucas
4.1.1
79e253e
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.
Compare
Choose a tag to compare
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

A:

Person
  type: AnotherPerson[]

B:

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
Loading

Changes in AMF 4.1.0

16 Apr 21:04
@BlockLucas BlockLucas
4.1.0
b9e2253
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.
Compare
Choose a tag to compare
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
Loading