Changes in 5.0.0-beta.4

Additions

Expose new ClasspathResourceLoader to load artifacts from class path

Why?: adopter request
Note: this Resource Loader is not added by default in the Configuration objects because it is Java/Scala specific. Fully qualified name is: amf.core.client.platform.resource.ClasspathResourceLoader

Added toString method in AMFResult

Why?: adopter request. Returns a string representation of the AMFResult instance similar to that of the AMFValidationReport

Added platform Annotations accessors to the Scala interface

Why?: scala adopters coming from the java interface didn't have the same accessor methods they used before. This meant that new scala interface adopters had to re-implement these methods by themselves.

Added configuration generation based on a Spec

Why?: once the API was parsed using any of the composite configurations (APIConfiguration, WebApi, Oas, Raml) it wasn't clear how the user could create a configuration compatible with the guessed API spec to validate, transform or render. Now, the user can do:

var client = APIConfiguration.API().baseUnitClient()
var result = client.parse("some-uri")
var specConfig = APIConfiguration.forSpec(result.sourceSpec)
var validationReport = specConfig.baseUnitClient().validate(result.baseUnit)

Added ShapesConfiguration/ShapeElementClient class

Why?: we moved shape specific methods to the ShapeElementClient class for amf-shapes only adopters. Adopters that used the shape render methods: toJsonSchema/toRamlDataType with the AMFElementClient will continue to be able to use them from that class.

Changes

Extracted RDF components to another artifact (amf-rdf) detached from the "main" artifact tree ("amf-api-contract" and "amf-aml")

Why?: this is the next step of removing SHACL as our validation engine. RDF functionality is used by a small amount of adopters and contributes a lot to the final production JAR / JS bundle size.

Important: for adopters that use Rdf functionality you will have to import the amf-rdf artifact in the same namespace as the rest of the amf artifacts.

Size impact on dependency tree:

• JS bundle (node_modules folder) / 5.0.0-beta.3 -> 27,9 MB; 5.0.0-beta.4 -> 14,5 MB / 48% size decrease
• JVM artifact (CLI uber jar) / 5.0.0-beta.3 -> 40,5 MB; 5.0.0-beta.4 -> 24,7 MB / 31% size decrease

Dialect ids parsed with parseContent is composed by: the default dialect uri and dialect name and version

Why?: several dialects parsed by content had the same id. If a user registered two different dialects parsed with the parseContent method then they override each others configuration. Adding the name and version to the id resolves that issue.

Linkable link methods were changed for Java / Javascript compatibility

Why?: the link(label: Option[String] = None) was split into: link() and link(label: String)

Removed payloadValidatorFactory method. Payload Validator creation is now via the AMFElementClient -> payloadValidatorFor method

Why?: reduce the public interface area that a user has to deal with by associating the AMFElementClient with payload validation.

Unified AML scala and platform interfaces

Why?: AML platform and scala interfaces were too different making it difficult for users that used both scala/platform packages to use AML classes in similar ways. Besides, it improves interface maintainability.

Removed Example.toJson/toYaml/toXml methods and replaced them for the renderExample method.

Why?: decouple example rendering from the Example model itself. This will enable the emission of the example in several formats if they are plugged into the configuration.

val client = ShapesConfiguration.predefined().elementClient()
val example = // get an Example
client.renderExample(example, "application/json") // predefined supported mediatypes are "application/yaml" | "application/json" | "application/xml"*

* If the example is obtained from an XML document as String

Updated typings

Note: added the link methods to typings and changed the non-existant lexical accessor for position. Added typings for the additions to the public interface.

Changes in AMF 4.7.7

Released Aug 27, 2021.

JS asset

JVM asset

RAML 1.0 changes

Parsing nil types

As the RAML Spec declares, nil types are equivalent to union types. However, this was not the case previously in AMF. In AMF 4.7.7 this has been changed and both notations are equivalent.

This change fixed some bugs, for example: Given the following similar RAML types:

types:
  def1?:
    type: integer
    default: 20
  def2:
    type: integer | nil
    default: 20
  def3:
    type: integer?
    default: 20

AMF didn't keep the default value in def3, thus causing an error when validating against that type. Now AMF correctly parses nillable notation and saves default and other facets in that object.

Properties declared in required field

AMF now saves properties declared in required but not present in properties. For example, consider the following JSON Schema:

{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "type" : "object",
    "properties": {
        "name": {"type": "string"},
        "age": {"type": "integer"}
    },
    "additionalProperties": false,
    "required": [
        "address"
    ]
}

Previously, AMF ignored property address as it was not declared in properties. Now it saves it and requires it in validation.

This change solved problems when using JSON Schemas with anyOf or oneOf and multiple schemas with only required fields.

For example, given the following JSON Schema:

{
    "type": "object",
    "oneOf": [
        {
            "required": [
                "p_1"
            ]
        },
        {
            "required": [
                "p_2"
            ]
        }
    ]
}

Previously AMF ignored properties p_1 and p_2, it parsed two empty schemas where any value would match, thus making it impossible to match with only one of those. Now AMF parses two schemas, one where p_1 and other where p_2 is required.

GitHub fixed issues

• #869
• #874
• #880
• #1085

AMF Fixed issues

• APIMF-3303 - Fixed errors "X should NOT have additional properties and "X should match some schema in Y"
• APIMF-3025 - Not validating oneOf schema correctly involving empty schemas with required
• APIMF-2975 - Cannot define required facet in property with nillable shorthand type
• APIMF-2973 - Default value is not parsed correctly when type is defined nullable

Changes in 5.0.0-beta.3

Changes

Removed spec related media types from our interfaces to avoid redundancy

Why?: Previously in beta.2 when rendering, validating and transforming users had to specify the mime type of the specification even if they were using a specific configuration like RAMLConfiguration.RAML10(). This led to redundant code such as:
RAMLConfiguration.RAML10().createBaseUnitClient().render(unit, ProvidedMediaTypes.RAML10)
Now all operations will obtain the specification type directly through the usage of specific configurations. The same use case as above can now be acheived through a more concise code:
RAMLConfiguration.RAML10().createBaseUnitClient().render(unit)
Specific changes for each operation:

• parse: client.parse(url) method will only receive one parameter for the path of the root file. For the case of client.parseContent(content, mediaType) an optional media type parameter is available only to provide the syntax of the content.
• transform: The PipelineName parameter, which contained the specification type, no longer exist as only the pipeline id can be provided. An example for transforming with Editing pipeline would be client.transform(unit.baseUnit, PipelineId.Editing).
• render: client.render(unit, mediaType) now receives an optional mediaType to provide the syntax of the result, while the specification type will depend on the configuration being used. Note: for the case of rendering jsonld `application/ld+json' media type can be used with any configuration.
• validate: client.validate(unit) no longer receives the optional parameter ProfileName as this value is obtained directly through the configuration used.

Limit usage of composite configurations to parsing

Why?: Composite configurations such as APIConfiguration.API() which contain capabilities for more that one specification can only be used for parsing. We have maintained this functionality as it offers AMF users the possibility of parsing any content without knowing the specification type beforehand. Any other operation that is invoked when using composite configuration will result in errors, such as rendering, transformation, or validation.

New Spec class returned in AMFParseResult

Why?: Due to the multi-spec parsing functionality explained above, we have included a new value in AMFParseResult which provides the specification type that was parsed. This is essential for users that use multi-spec parsing because through the Spec value they will know which specific configurations they need to use for other operations such as transformation or validation.

Removed merging capabilities of configurations

Why?: Since the use of specific configurations is essential for the correct functioning the majority of AMFs operations, we have eliminated the possibility of merging different configuration as this would lead to inconsistent functionality.

Removed jena-shacl dependency for amf-validation artifact

Why?: The SHACL validator provided by jena has been fully replaced by our own implementation, allowing us to exclude this dependency.

Fixes

Fixed parsing of yaml content when using parseContent interface with no specified media type

Why?: In beta.2 when using the parseContent interface if the string was in a yaml format AMF was unable to parse it correctly returning an ExternalFragment. It is now capable of parsing yaml content correctly returning its corresponding Document.

Fixed ValueField hierarchy in JS typings

Why?: The actual hierarchy of ValueField classes was not represented correctly in the typings, leading to compilation errors.

Add resource fetching capabilities to ShapeValidationConfiguration

Why?: Our existing payload validation plugin implementations where fetching files and did not have this functionality available in the previous interface.

Avoid error when parsing JSON-LD with non scalar annotations

Why?: In beta.2 unclear validations where returned in the parsing result.

Changes in 4.7.6

Released July 27, 2021.

JS asset

JVM asset

RAML 1.0 - Validation of duplicate properties in data type

Given the following invalid type definition with duplicated property names:

types:
  failing:
    type: object
    properties:
      a: string
      a?: string
    example:
      a: "some example"

AMF was throwing an unrelated violation in JVM, but nothing in JS. A new violation has been added to make the error clearer in both platform, AMF now returns:
Duplicated property names: a

Dependencies Changes

Updated

• org.apache.commons % commons-compress moved from 1.19 to 1.21
• ajv javascript dependency moved from 6.5.2 to 6.12.6

AMF Fixed issues

APIMF-3232 - Analyze ajv dependency update
APIMF-3212 - Adding an enum property in an extension duplicates values
APIMF-3211 - RAML inline union in extension not parsing correctly
APIMF-3209 - Missing validation for properties with same name in raml type
APIMF-3097 - SE: Anypoint Design Center doesn't allow uses of the same library multiple times
APIMF-3096 - java.lang.ArithmeticException: Division by zero with multipleOf facet

Changes in 5.0.0-beta.2

Changes

Added AMFElementClient

Why?: this new client holdscommon operations associated to shapes, such as serializing to Json Schema or RAML, render a domain element and others.

Renamed AMFClient to AMFBaseUnitClient

Why?: distinguish between ElementClient and BaseUnitClient.

Changed Vendor for mediaType: String in ApiDomainElementEmitter

Why?: beta.2 uses mediaTypes instead of Vendors to serialize domain + syntax

Deleted AMFLogger

Why?: its usage overlapped with AMFEventListener.

Renamed bu to baseUnit in AMFResult for the amf.*.client.scala* packages

Why?: to have consistency between scala and platform interfaces

Removed Shape constructors from the public scope

Why?: the primary constructors in the Shape hierarchy used internal argument that shouldn't be used by the end user.

Added LoaderWithExecutionContext helper interface for ResourceLoaders that have to use ExecutionContext

Why?: resource loaders that implement this interface will have their execution context updated whenever the *.Configurations execution context is updated.

Unified RenderOptions with ShapeRenderOptions

Why?: having two kinds of RenderOptions that were nested was confusing.

Added transformPipelineWithId method.

Why?: transform.* methods can be difficult to use as the users have to tell which pipeline they want to use and which spec their BaseUnit was parsed from.

Fixes

Fixed AMFErrorHandler being shared between runs

Why?: this bug caused parsing errors to "leak" between operations. This was only repeatable when using the same configuration for multiple operations.

Explicitly registered SHACL and Ajv to the global scope in JS script

Why?: fix that was added to 4.x.x but wasn't cherry-picked to this version.

Fixed amf.*.client.scala types leaking in amf.*.client.platform classes

Why?: this made very hard for platform adopters, especially users of the JS bundle, to use client classes as amf.*.client.scala classes are not exported to Javascript.

Added JS native object construction for EventListeners

Why?: JS users couldn't plug-in JS objects that respected the AMFEventListener interface. Now they should use the AMFEventListenerFactory to create them.

Added parenthesis to JS exported functions in RenderOptions to make it more "js-like" for JS adopters

Why?: method chaining with Scala no-param functions seems odd in Javascript as they can't be used from that language. For example:

new RenderOptions().withPrettyPrint.withCompactUris.withoutSourceMaps.withFlattenedJsonLd

Adding parenthesis to those methods while useless in Scala makes it easier to read and more natural to JS adopters:

new RenderOptions().withPrettyPrint()
.withCompactUris().withoutSourceMaps().withFlattenedJsonLd()

Renamed ValidationResult to AMFValidationResult

Why?: for consistency between *.scala* and *.platform* interfaces

Added Native JS payload validator interfaces

Why?: similar to the EventListeners change, AMF Payload Validation plugins couldn't be plugged in from Javascript. We added the AMFPayloadValidationPluginConverter static class to convert native js payload validation plugins to Scala ones to be able to plug them in the AMF configuration instance.

Changes in 5.0.0-beta.1

Changes

Removed withoutFlattenedJsonLd from the public scope in RenderOptions

Why?: as embedded json-ld parsing is deprecated and emission was removed, it didn't make sense to have a render option that let the user emit json-ld in the embedded form.

Removed ExecutionLog and replaced it for EventListeners

Why?: we replaced the ExecutionLog functionality with event listeners as it was part of the static state that we aim to remove in this beta.

Fixes

• Added AsyncCachePipeline to the AsyncAPIConfiguration
• Added ExecutionEnvironment setter in AMFConfiguration

Changes in 4.7.5

Released June 29, 2021.

JS asset
JVM asset

Interface Changes

Loading validation profiles from strings

There is a new method to load custom validation profiles from a string

Added

• amf.client.validate.Validator.loadValidationProfileString(..)

AMF Fixed issues

APIMF-3103: added interface to load validation profile from string
APIMF-3021: fix raml08 parameter not being added to entries in oas request parser
APIMF-3118: Issue parsing API with APISync resource loader
APIMF-3125: Issue parsing OAS3 API with APISync resource loader
APIMF-3160: Custom domain properties are not parsed from JSON-LD with compact uris
ALS-1532: Fix annotation on referenced example
Fix CLI jar assembly

Changes in 4.7.4

Released June 3, 2021.

JS asset

JVM asset

Lexical information optimization

Additions and corrections were made on the lexical information

Interface Changes

NullSecurity annotation exposed in ParametrizedSecurityScheme

There is a new method in ParametrizedSecurityScheme to check if a security scheme is null and not "null".

Added

• amf.client.model.domain.ParametrizedSecurityScheme.hasNullSecurityScheme(..)

AMF Fixed issues

APIMF-3129 - Examples field with empty object causes exception
APIMF-3127 - Error with numeric names in traits
APIMF-3115 - AMF fails to parse DiscriminatorValueMapping nodes in JSON-LD
APIMF-3061 - RAML datetime-only validation doesn't check year with 5 digitals
APIMF-3020 - Unable to use amf.js as an ES module due to bad syntax Github Issue #888
APIMF-2601 - Improve/add annotations tests for AsyncApi 2.0
APIMF-2600 - Improve/add annotations tests for OAS 3.0
APIMF-2599 - Improve/add annotations tests for OAS 2.0
APIMF-2597 - Improve/add annotations tests for RAML 0.8
APIMF-2566 - Improve/add annotations tests for RAML 1.0
APIMF-3120 - Provide way to access NullSecurity annotation from client

Changes in 4.7.3-1

Released May 4, 2021.

JS asset

JVM asset

OAS 3.0 discriminator mappings

Node shapes parsed from OAS 3.0 schemas which define a mapping for the discriminator facet now have a new field called DiscriminatorValueMapping field that holds the relation discriminator value with the corresponding parsed target for that discriminator value.

AMF Fixed issues

APIMF-3062 - Invalid discriminator mapping values result in violation and NPE
APIMF-3060 - Release Bug: Error resolving paths in RAML08
APIMF-3059 - Release Fix - !include with spaces not being resolved
APIMF-3057 - Content.stream is not accesible
APIMF-3045 - Analyze performance of slow API in API Designer
APIMF-3034 - Fix resolution for self-encoded dialect instances
APIMF-3033 - Support cyclic reference parsing in AMF Flattened JSON-LD parser
APIMF-3023 - AMF provides wrong path to the provided resource loader
APIMF-2988 - Recursive shape inexistent fixpoints analysis
APIMF-2987 - Incorrect fix point value in RecursiveShape
APIMF-2980 - Refactor constraints validation plugins to support all contraints
APIMF-2966 - Oas Type Parsing with nullable as single map entry creates a UnionShape
APIMF-2963 - Implement: parsing plugin dependencies
APIMF-2944 - Unify creation of enum validation candidates in payload validation
APIMF-2920 - Link referenced Shape by JSON pointer in OAS 3 Discriminator mapping
APIMF-2909 - Move Dialect indexation to new plugins logic
APIMF-2901 - Debug Windows issue during resolution
APIMF-2601 - Improve/add annotations tests for AsyncApi 2.0

Changes in 4.7.2

Released April 8, 2021.

JS asset

JVM asset

AMF Fixed issues

APIMF-2461 - Declares node is not being emitted in some Dialect Instances although present in JSON-LD
APIMF-2986 - UrlShorteningStage not applied to RecursiveShape fix point in external library
APIMF-3005 - Parse allowMultiple property mappings with single elements in JSON-LD
APIMF-2962 - JSON-LD parsing with AMF GraphParser is slower than Jena + RDF model parser
APIMF-2930 - Tracked Element annotation is not being rendered for RDF
APIMF-2954 - Compatibility Pipeline OAS to RAML is not resolving mediatypes
APIMF-2876 - Duplicated id: query and header parameters in RAML 1.0
APIMF-2934 - Nillable shorthand types don't work in parameters
APIMF-2890 - Analyze support for linking RecursiveShape when parsing
APIMF-2965 - Invalid nodes in unions are not validated
APIMF-2600 - Improve/add annotations tests for OAS 3.0
APIMF-2943 - Analyze reconstruction of MutRef when emitting DataNode