Any versions that are not listed here should be avoided. They may be broken images, contain serious known-broken behavior, accidentally introduce an incompatible change in a point release, or contain a known security issue.
For brevity, only the latest patch version will be listed for each minor release version. For example, the entry for 0.48.5 includes any changes that may have previously been released under 0.48.2.
JDK 21
2.6.3 – Table valign, breakout mark on panel, wiki table in list parsing
ABJL-6: ADF Change 98: allow valign on table cells/headers
EDITOR-7934: ADF Change 104: allow breakout mark on rule and panel nodes
JRACLOUD-81739: Add feature gate ListParser.PARSE_TABLES_IN_LIST_ITEMS to parse tables within list item. ADF still doesn’t allow this, so they break up the containing list, but at least this permits the table to still parse rather than be treated as literal text.
2.5.1 – Nested lists enabled; code block attrs in full schema
ADF Change 94: Feature.ALLOW_NESTED_LISTS_AS_FIRST_CHILD deprecated / now forced on
ADF Change 94: Wiki markup context feature ListBuilder.ALLOW_NESTED_LIST_AS_FIRST_ITEM to remove the extra blank paragraph insertion during Wiki-to-ADF conversions
ADF Change 90: New codeBlock attrs available in full schema
2.5.x Upgrade Notes
Anyone using adf-builder-java-wiki to convert from Wiki to ADF should roll out ListBuilder.ALLOW_NESTED_LIST_AS_FIRST_ITEM before upgrading to (TBD: version that no-ops this feature) or later.
2.4.0 – Improved HTML parsing available as opt-in
ABJL-3: Improvements to HtmlParser, currently opt-in with .useEnhancedParser()
2.4.x Upgrade Notes
The HtmlParser.useEnhancedParser() feature guard will likely only remain active for a short time. Consumers of adf-builder-java-html are advised to upgrade to this version and perform a safe rollout of this feature before upgrading to (TBD: version that no-ops this feature) or later.
2.3.1 – Jackson 3 support
ABJL-7 TC-48917: Jackson 3 support
CRCS-5199: Render URL from blockCard and embedCard in plaintext (feature-gated)
2.2.6 – Context.GlobalDefaultFeatureProvider
New mechanism to make it easier for applications to manage the feature flag configuration globally by changing the default per-thread feature provider.
Nested lists as first child element still behind Feature gate, but promoted to full schema
Support for paragraph with fontSize mark
ABJL-5: Fix custom panel icon handling; add new icon() and icon(Emoji) methods
ADF Change 94: ability to nest lists without a placeholder empty paragraph first, (feature-flagged)
ADF Change 95: fontSize mark for paragraphs
ADF Change 97: allow dataConsumer on media and mediaInline nodes
2.1.x Upgrade Notes — IMPORTANT!!!
*WARNING!!! *Feature.ALLOW_NESTED_LISTS_AS_FIRST_CHILD **is a significant change to the library behaviour. **Consumers of this library are strongly advised to perform a safe rollout of this feature immediately to ensure interoperability with other systems and before upgrading to 2.5.x or later.
2.0.10 – JDK 21, dropping Jackson 1 and Scala PlayJson, leading space in links
JSDCLOUD-18412: Fix for [ text|url] invalid wiki generation
145: ACTIVATION-193: continued improvements to DocX support (EXPERIMENTAL)
2.0.x Upgrade Notes
MINIMUM JDK 21
Removal of @Deprecated methods:
com.atlassian.adf.model.Schema.url() – Leaked internal detail; no replacement
com.atlassian.adf.model.Schema.inputStream() – Leaked internal detail; no replacement
com.atlassian.adf.model.node.LayoutSection.Partial.NeedsSecondColumn – A single column is now sufficient, so this incomplete builder state no longer exists
com.atlassian.adf.model.node.type.Marked.mark(String) – Use marks(Class) or mark(MarkKey) instead
com.atlassian.adf.util.Sanitizer.sanitize(Doc) – Removed to reduce any possible confusion about its behavior. Use sanitizeMutate(Doc) instead
com.atlassian.adf.schema.SchemaValidator.getInstance() – Use full() or stage0() explicitly
com.atlassian.adf.schema.SchemaValidator.useExperimentalValidator() – No replacement, as it had no effect in 1.x anyway.
com.atlassian.adf.wiki.encoder.nodes.TableEncoder.PROTECT_HARD_BREAKS – No replacement, as this feature is fully released
Except: Anything related to the link type value for media and mediaInline will be retained indefinitely to support backward-compatibility of the schema
Other incompatible changes:
com.atlassian.adf.model.node.LayoutSection.Partial.NeedsFirstColumn.content(LayoutColumn) – Return type is now LayoutColumn as part of removing the NeedsSecondColumn state, which will break binary-compatibility but not source-compatibility.
Several exception classes changed internal field storage from Object to Serializable, which is unlikely to affect consumers.
Dropped support for Jackson v1 – Consumers will have to maintain this themselves from now on. Example source: [→ AdfJackson1.java]
Dropped support for Scala PlayJson – Consumers will have to maintain this themselves from now on. Example source: [→ AdfPlayJson.scala]
2.0.7 – JDK 21, dropping Jackson 1 and Scala PlayJson, leading space in links
JSDCLOUD-18412: Fix for [ text|url] invalid wiki generation
145: ACTIVATION-193: continued improvements to DocX support (EXPERIMENTAL)
Upgrade Notes
MINIMUM JDK 21
Removal of @Deprecated methods:
com.atlassian.adf.model.Schema.url() – Leaked internal detail; no replacement
com.atlassian.adf.model.Schema.inputStream() – Leaked internal detail; no replacement
com.atlassian.adf.model.node.LayoutSection.Partial.NeedsSecondColumn – A single column is now sufficient, so this incomplete builder state no longer exists
com.atlassian.adf.model.node.type.Marked.mark(String) – Use marks(Class) or mark(MarkKey) instead
com.atlassian.adf.util.Sanitizer.sanitize(Doc) – Removed to reduce any possible confusion about its behavior. Use sanitizeMutate(Doc) instead
com.atlassian.adf.schema.SchemaValidator.getInstance() – Use full() or stage0() explicitly
com.atlassian.adf.schema.SchemaValidator.useExperimentalValidator() – No replacement, as it had no effect in 1.x anyway.
com.atlassian.adf.wiki.encoder.nodes.TableEncoder.PROTECT_HARD_BREAKS – No replacement, as this feature is fully released
Except: Anything related to the link type value for media and mediaInline will be retained indefinitely to support backward-compatibility of the schema
Other incompatible changes:
com.atlassian.adf.model.node.LayoutSection.Partial.NeedsFirstColumn.content(LayoutColumn) – Return type is now LayoutColumn as part of removing the NeedsSecondColumn state, which will break binary-compatibility but not source-compatibility.
Several exception classes changed internal field storage from Object to Serializable, which is unlikely to affect consumers.
Dropped support for Jackson v1 – Consumers will have to maintain this themselves from now on. Example source: AdfJackson1.java
Dropped support for Scala PlayJson – Consumers will have to maintain this themselves from now on. Example source: AdfPlayJson.scala
146: schema 50.1.1, adding localId attributes to most nodes and new blockTaskItem
1.7.1 – schema changes, extension nesting
142: correction to multiBodiedExtension’s marks section in the stage-0 schema
143: ADF Change 85: extension nesting
extension within blockquote, listItem, nestedExpand, and panel
51: revert changes made for CS consistency
codeBlock – revert including attrs even when empty
paragraph – revert including content even when empty
1.6.0 – Context/Feature API for core library, mention id in plaintexxt
CRCL-3421: introduce ability to render plaintext mentions as @[id] instead of @unknown
CRCL-3421: to support rolling that out safely, introduce Context/Feature API and hide it behind Feature.PLAINTEXT_MENTION_USE_ID
1.5.0 – schema changes, stage-0 support
142: schema changes
schema 47.2.0
core library now packages both the stage-0 and full schemas
schema-related APIs allow caller to specify which schema to use
core library node always follow stage-0 schema; see Upgrade Notes
new nodes: multiBodiedExtension, extensionFrame
new mark use: date, emoji, mention, and status can now accept annotation
142: several marker interfaces now narrow the return type for copy()
1.5.x Upgrade Notes
Going forward, the core library is going to start tracking the stage-0 schema instead of the full schema. In practice, this means that it may be possible to build documents with the library that will pass validation for the stage-0 schema but will be rejected by the full schema. Generally, Confluence supports the stage-0 schema while Jira only supports the full schema, so this should be kept in mind.
At the time of this release, the only stage-0 feature that impacts Jira is placing a blockquote inside a panel. While the library now supports this nesting, Jira will not accept that structure until it is available in the full schema.
1.0.0 – SOX compliance; API stability
131: SOX compliance controls; API stability
1.0.x Upgrade Notes
There are no functional changes between 0.52.2 and 1.0.0. As per Semantic Versioning, the bump from 0.x.x to 1.0.0 indicates that the library has moved from the initial development phase to the public API phase, and it is a formal commitment to maintain API stability going forward.
The schema validator’s transitive dependencies changed, with the result that most of its previous dependencies, like Guava and Joda-Time, are no longer required.
Although the schema validator’s Result object is not changed, the actual string contents of its message will look very different from before. This is likely to change again in the future and should not be considered an API.
The public API utility class Colors has a few methods renamed in ways that are not backwards-compatible. In particular, isHex is now isHex3or6 to clarify that the hex8 format (with an alpha channel) is not tolerated by that method. With apologies to anyone affected, this change seemed worth the risk.
0.44.2 – Experimental schema validator
109: experimental opt-in bespoke schema validator
112: reorder fields for consistency with content service
113: reorder fields for consistency with content service