Releases: aml-org/amf
5.6.3
What's Changed
- W-16847560: use the same json schema version mapping in raml and oas by @arielmirra in #2052
- W-16712475 - Added parsing option allowing to parse extensions in eve… by @looseale in #2053
- W-16930843 - Some dependency bumps by @looseale in #2054
- W-16888404: change parameter description parsing and bump model by @arielmirra in #2055
Full Changelog: 5.6.2...5.6.3
5.6.2
Bug fixing
- Fixed bug in avro validation related with inner union schemas with default values
What's Changed
- Release 5.6.1 to develop by @looseale in #2046
- W-16772136 - Minor changes in Avro ADR due last library changes (naming) by @looseale in #2047
- W-16837997 - Avro union fixes by @looseale in #2048
- Publish 5.6.2 by @looseale in #2049
Full Changelog: 5.6.1...5.6.2
What's new in AMF 5.6.1
AVRO Support in AMF
We're happy to announce we've added support for AVRO Schema 1.9.0 in AMF:
- as a standalone document
- inside Async APIs
an AVRO Schema has the following properties:
- It's defined in a
.json
or.avsc
file - It doesn't have a special key that indicates it's an AVRO Schema, nor it's version (like JSON Schema does with it's
$schema
)
Where we support and DON'T support AVRO Schemas
We Support AVRO Schemas (inline or inside a $ref
):
- as a standalone document or file
- we encourage users to use the
.avsc
file type to indicate that's an avro file - must use the specific
AvroConfiguration
- we encourage users to use the
- inside a message payload in an AsyncAPI
- the key
schemaFormat
MUST be declared and specify it's an AVRO payload
- the key
- an
AvroSchemaDocument
can only be parsed with the specificAvroConfiguration
We don't support AVRO Schemas:
- inside components --> schemas in an AsyncAPI
- because we can't determine if it's an AVRO Schema or any other schema
Known AVRO Validation limitations
We're using the Apache official libraries for JVM and JS. The validation libraries differ in interfaces and implementations, and each has some known constraints:
JVM avro validation constraints
- validation per se is not supported, we try to parse an avro schema and throw parsing results if there are any
- this means it's difficult to have location of where the error is thrown, we may give an approximate location from our end post-validation
- when a validation is thrown, the rest of the file is not being searched for more validations
- this is particularly important in large avro schemas, where many errors can be found but only one is shown
Both JVM & JS validation constraints
"default"
values are not being validated when the type isbytes
,map
, orarray
- the validator treats as invalid an empty array as the default value for arrays (
"default": []
) even though the Avro Schema Specification has some examples with it - if an avro record has a field that is a union that includes the root record itself (recursive reference) we fail to validate it correctly because we treat that shape as an unresolved/undefined shape. This only applies to the field inside the record, when validating the complete record the library validates correctly. In the future we'll try to ignore the cases that we are now failing and/or show a warning instead
More information here
for more information on how to use AVRO in amf check the adrs/0014-avro-support.md
file.
Full Changelog: 5.5.4...5.6.1
What's new in AMF 5.6.0
AVRO Support in AMF
We're happy to announce we've added support for AVRO Schema 1.9.0 in AMF:
- as a standalone document
- inside Async APIs
an AVRO Schema has the following properties:
- It's defined in a
.json
or.avsc
file - It doesn't have a special key that indicates it's an AVRO Schema, nor it's version (like JSON Schema does with it's
$schema
)
Where we support and DON'T support AVRO Schemas
We Support AVRO Schemas (inline or inside a $ref
):
- as a standalone document or file
- we encourage users to use the
.avsc
file type to indicate that's an avro file - must use the specific
AvroConfiguration
- we encourage users to use the
- inside a message payload in an AsyncAPI
- the key
schemaFormat
MUST be declared and specify it's an AVRO payload
- the key
- an
AvroSchemaDocument
can only be parsed with the specificAvroConfiguration
We don't support AVRO Schemas:
- inside components --> schemas in an AsyncAPI
- because we can't determine if it's an AVRO Schema or any other schema
Known AVRO Validation limitations
We're using the Apache official libraries for JVM and JS. The validation libraries differ in interfaces and implementations, and each has some known constraints:
JVM avro validation constraints
- validation per se is not supported, we try to parse an avro schema and throw parsing results if there are any
- this means it's difficult to have location of where the error is thrown, we may give an approximate location from our end post-validation
- when a validation is thrown, the rest of the file is not being searched for more validations
- this is particularly important in large avro schemas, where many errors can be found but only one is shown
Both JVM & JS validation constraints
"default"
values are not being validated when the type isbytes
,map
, orarray
- the validator treats as invalid an empty array as the default value for arrays (
"default": []
) even though the Avro Schema Specification has some examples with it - if an avro record has a field that is a union that includes the root record itself (recursive reference) we fail to validate it correctly because we treat that shape as an unresolved/undefined shape. This only applies to the field inside the record, when validating the complete record the library validates correctly. In the future we'll try to ignore the cases that we are now failing and/or show a warning instead
More information here
for more information on how to use AVRO in amf check the adrs/0014-avro-support.md
file.
Full Changelog: 5.5.4...5.6.0
5.5.4
AVRO transformation and rendering support (ALPHA)
In the previous release we added support for AVRO parsing, which means creating an AvroConfiguration
with an AvroParsePlugin
and with that create a BaseUnitClient
that has the parse()
method that parses an AVRO Schema and returns an AvroSchemaDocument
.
This release, we've added support for the transform()
and render()
methods, letting the user resolve the model and export it to .jsonld
or to .json
again.
To do this, we've created the AvroRenderPlugin
and added it to the AvroConfiguration
as well as the necessary transformation pipelines. Now the AVRO Configuration is much more complete and looks like this:
object AvroConfiguration extends APIConfigurationBuilder {
def Avro(): AMFConfiguration = {
common()
.withPlugins(List(AvroParsePlugin, AvroRenderPlugin))
.withTransformationPipelines(
List(
AvroSchemaTransformationPipeline(),
AvroSchemaEditingPipeline(),
AvroSchemaCachePipeline()
)
)
}
}
We're expecting to continue this growth and launch AVRO Validation in the next release, will keep you updated.
For more information about transformation and rendering check the following documentation:
What's Changed
- W-16124325 -Avro interfaces by @looseale in #2015
- release/5.5.3 to develop by @looseale in #2018
- W-16006973: add AVRO ADR by @arielmirra in #2019
- W-16006973: add avro-schema annotation on collections (items/values) parsing by @arielmirra in #2020
- W-16006973: add avro annotations by @arielmirra in #2021
- W-16246407 - Fix handle of method string kind by @looseale in #2022
- W-15633231: add AVRO basic resolution pipelines by @arielmirra in #2023
- W-15633198: add AVRO emission by @arielmirra in #2024
- W-15633239 - AvroSchemaDocument ref handle by @looseale in #2025
- W-15633231: add avro transformation pipelines and tests by @arielmirra in #2026
- W-16346159: fix parsing avro record field without a type defined by @arielmirra in #2027
- W-16346159: AVRO fixes by @arielmirra in #2028
Full Changelog: 5.5.3...5.5.4
5.5.3
AVRO Support (ALPHA)
AVRO Schema Support in Async
Added support to parsing of AVRO Schemas in Async 2.x payload definitions (inlined or referencing to an external file).
This support is currently limited, only for parsing, not for validation or emission.
AVRO Schema Fragment
Added support to parsing of AVRO Schemas as a fragment using the new AvroConfiguration
, returning an AvroSchemaDocument
. This is only for AVRO Schema files parsed using this specific configuration, files referenced from an Async 2.x API will be processed as ExternalFragment
as usual.
This support is currently limited, only for parsing, not for validation or emission.
What's Changed
- W-15770660 Publish 5.5.2 dev by @damianpedra in #2004
- W-15847817. Minor performance improvements by @jisoldi in #2001
- W-15847817. Golden files regenerated after some order changes in annotations. by @jisoldi in #2005
- W-15904614 - Some Lexical fixes by @looseale in #2008
- W-15633176: add initial AVRO Schema parsing by @arielmirra in #2009
- W-15633176: fix record fields parsing by @arielmirra in #2011
- W-15633213: Add TCK for avro schemas by @damianpedra in #2013
- W-16124325 - Avro interfaces by @looseale in #2014
- W-16124325 - Publish 5.5.3 by @looseale in #2016
- W-16124325 - Publish 5.5.3 by @looseale in #2017
Full Changelog: 5.5.2...5.5.3
5.5.2
What's Changed
This release finished the support for multiple binding versions, enhancing the flexibility and compatibility of our platform. The new bindings include updates for Solace, Kafka, AMQP, HTTP.
In the spec, by default if not present, the version of the binding is the latest. We chosen to ignore this behavior, because it could lead to a broken AsyncAPI contract when a new version of the binding is introduced. Instead of that. This approach prevents breaking changes for users relying on the latest versions. By defaulting to these versions, we maintain consistency and ensure that essential fields are supported without introducing unexpected incompatibilities.
Default Binding Versions
The default binding versions have been selected to ensure stability:
-
Solace:
- async 2.0 to async 2.6 default version is 0.3.0
-
AMQP:
- async 2.0 to async 2.6 default version is 0.2.0
-
HTTP and GooglePubSub:
- async 2.0 to async 2.6 default version is 0.1.0
-
MQTT:
- async 2.0 to async 2.6 default version is 0.1.0
-
AnypointMQ:
- async 2.0 to async 2.6 default version is 0.0.1
-
Kafka Bindings version:
- KafkaOperationBinding and KafkaMessageBinding
- Async 2.0 default version is 0.1.0
- KafkaOperationBinding and KafkaMessageBinding
- Async 2.1 to 2.6 the default version is 0.3.0
- KafkaServerBinding and KafkaChannelBinding
- Async 2.1 to 2.6 the default version is 0.3.0
- KafkaOperationBinding and KafkaMessageBinding
-
Pulsar:
- Async 2.0 to async 2.6 default version is 0.1.0
-
Mercure:
- Async 2.0 to async 2.6 default version is 0.1.0
-
W-15425041: release-fix: remove '.' in fields id and displayNames by @arielmirra in #1983
-
W-15696514: change amqp binding default version to 0.2.0 by @arielmirra in #1990
-
W-15570769: fix oas components unresolved ref violations by @arielmirra in #1988
-
W-15425041: support HTTP binding versions 0.1.0, 0.2.0, and 0.3.0 by @arielmirra in #1987
-
W-15425034: add google binding version 010 & 020 by @arielmirra in #1996
-
W-15425058: add mqtt version 010 & 020 by @arielmirra in #1997
-
W-15425062: Add support for Solace Binding Versioning by @damianpedra in #1982
-
W-15425058: fix solace operation topic by @arielmirra in #1998
-
W-15845362 - Fixed some missing matches with new Async 2.x Specs by @looseale in #1999
-
W-15643510-fix default version fon bindings by @damianpedra in #2000
Full Changelog: 5.5.1...5.5.2
5.5.1
What's Changed
- W-14931280: add complete asyncApi for 2.1 and 2.2 fixing syntax by @damianpedra in #1957
- W-14931493: Fix from Spec by @looseale in #1959
- W-14931280: Add Reolution test for new stages by @damianpedra in #1960
- W-15092041: Bump model version to 3.9.0 by @looseale in #1963
- W-15092041: Adding typings related to Async 2.x by @looseale in #1965
- W-15092041: fix ibmmq validations false negatives by @arielmirra in #1968
- W-15510077: Some fixes detected in async 2.x by @looseale in #1973
- W-15053193: Simple modification of methods AmfUpdaterIterator.hasNext and AmfUpdaterIterator.next to be tailrecursive. by @jisoldi in #1975
- W-15425021: Amqp binding versioning 0.1.0-0.3.0 by @arielmirra in #1974
- W-15520216: Fix asyncApi-2.x-all examples by @looseale in #1976
- W-15425021: Add AnypointMQ Binding to support references by @damianpedra in #1978
- W-15425051: support kafka 0.1.0, 0.2.0 and 0.3.0 by @arielmirra in #1979
- W-15555945: Fix SYAML conversion using casting with handling by @looseale in #1980
- W-15425051: support kafka binding 0.5.0 by @arielmirra in #1981
- W-15378866: remove '.' in fields id and displayNames by @damianpedra in #1984
Full Changelog: 5.5.0...5.5.1
Changes in AMF 5.5.0
What's changed
Added parsing, transformation, validation and emission support for Async 2.1 to 2.6
We've added support for Async 2.1, 2.2, 2.3, 2.4, 2.5, and 2.6 versions.
The new bindings are:
- Async 2.1 onwards:
Mercure
andIBMMQ
bindings support
- Async 2.2 onwards:
AypointMQ
binding support
- Async 2.3 onwards:
Solace
binding support
- Async 2.5 onwards:
GoglePubSub
binding support
- Async 2.6 onwards:
Pulsar
binding support
For more information about each binding check out the asyncapi bindings repository.
New AsyncApi transformation steps
We've added transformation steps that add more metadata to async APIs. While this features were added in specific async versions, we're running these steps to all Async APIs (2.x.x)
ChannelServersResolutionStage
- Specifies which servers apply to each channels (all servers by default unless specified)
OperationsSecurityResolutionStage
- Specifies which security schemes apply to each operation (all by default unless specified)
Async bindings versions limitations
At the moment of this release, for bindings that already existed with Async 2.0 (Kafka, Amqp091, HTTP, MQTT, WebSocket): we made no changes there, the code is the same that existed for Async 2.0, so the supported version is the 1.0.0 of each binding.
For new bindings added between Async 2.1 and Async 2.6 (Solace, Pulsar, AnypointMQ, IBMMQ, Googlepubsub): the supported version is the immediate previous to the Async 3.0 commit (feat!: release v3 compatible bindings).
We know this is not exactly the correct behavior, but we didn't detected this until some weeks ago (the spec is not very clear about it).
We'll be adding support for all the bindings versions to allow you to choose the desired version using the bindingVersion
field. This is coming in a future release.
Commits
- W-14875427 Publish 5.4.9 dev by @damianpedra in #1946
- W:12689961: Add ServerVariables to Components in Async 2.4 by @damianpedra in #1948
- W-15207889. Some performance improvements. by @jisoldi in #1949
- W-12689958: add Solace binding by @arielmirra in #1942
- W-12689966: add pulsar binding by @arielmirra in #1950
- W-12689962: add security schemes in operation bindings by @arielmirra in #1953
- W-14887698: fix scala and Platform interfaces for async 2.x by @damianpedra in #1954
- W-12689965 by @damianpedra in #1952
- W-14990427: add custom binding validations by @arielmirra in #1955
- W-14931493 - Exposed internal Async plugin by @looseale in #1956
- W-15092041: fix release 5.5.0 by @arielmirra in #1958
- Publish 5.5.0-RC.2 by @looseale in #1961
- bump amf model by @arielmirra in #1964
- Async2x typings by @looseale in #1966
- W-15092041: adopt amf-core 5.5.0-RC.1 by @arielmirra in #1967
- W-15092041: fix ibmmq validations false negatives by @arielmirra in #1969
- publish 5.5.0 setup by @arielmirra in #1970
- publish AMF 5.5.0 by @arielmirra in #1971
New Contributors
Full Changelog: 5.4.9...5.5.0
5.4.9
What's Changed
- W-14991650 (fix): fixed declaration keys setting in Async 2.0 by @tomsfernandez in #1929
- W-13925199 Publish 5.4.8 dev by @damianpedra in #1933
- W-12689952: add ibmmq binding in async21+ by @arielmirra in #1926
- W-12689953: add SASL security schemes by @arielmirra in #1934
- W-12689957 - Added new components for Async 2.3 by @looseale in #1925
- W-12689950: add name and summary to message examples by @damianpedra in #1936
- W-15039225 - Adding test for unhandled exception in RL by @looseale in #1937
- W-12689955: async2.2+ add channel servers by @arielmirra in #1935
- W 12689960 New field at messages: MessageId by @damianpedra in #1938
- W-12689956: add AnypointMQ binding by @arielmirra in #1939
- W-12689964: add tags in server for async 2.5 by @damianpedra in #1940
- W:12689964: fix async20Syntax for message by @damianpedra in #1941
- W-15176856 - Exclude dependency and publish 5.4.9-RC.1 by @looseale in #1943
Full Changelog: 5.4.8...5.4.9