Document

Structure d'un document AriaML

AriaML Document Structure

The AriaML standard defines a structured, identifiable, and interoperable document format. It is designed to be interpreted natively by browsers or e-readers, whether accessed on the web, opened as local files, or executed as applications (PWA).

  • An AriaML document has no doctype, nor html, head, or body tags.
  • It exists exclusively in UTF-8.
  • It is entirely embedded within an aria-ml tag.
  • It inherits from html and can contain the same elements as body.

1. Context Declaration and Namespace

AriaML document properties can be declared using a double semantic context. The AriaML context extends Schema.org capabilities to provide increased precision for control metadata.

{
    "@context": [
        "https://schema.org",
        "https://ariaml.com/ns/"
    ]
}
  • Priority: In the event of a property conflict, the https://ariaml.com/ns/ namespace takes precedence over general-purpose vocabulary.

2. Authorized Document Types

To be valid, the root document description must use one of the following types, defining the object's intended use:

  • Article: Predominantly editorial or textual content.
  • WebPage: A document exposed on a public network.
  • DigitalDocument: A standalone file, often used for local or editable documents.
  • SoftwareApplication: A document serving as an interface for an application or a PWA.

3. Identity and Fundamental Properties

The global identity of the document is defined by the block whose identifier (@id) is either absent, defined as an empty string (""), or the character #.

System Property Mapping:

The user agent must map the following JSON-LD properties to native interface components:

AriaML Property System / UI Component Description
name Document Title Defines the name displayed in the tab or title bar.
description Document Description Description of the content (equivalent to the meta description tag).
inLanguage Language Attribute Defines the processing language for speech synthesis and rendering.
direction Reading Direction Defines the flow orientation (e.g., ltr, rtl).
url Canonical Identifier The document's authoritative URL (rel="canonical").
author Author Link to the author's identity (rel="author").
license License Link to terms of use (rel="license").
csrfToken Security Security token for mutations (meta name="csrf-token").

metadatas are the equivalents of the <meta name="..."> tag. The JSON object associates a key (name attribute) with a value (content attribute). The properties list corresponds to <meta property="..."> tags, primarily used for Open Graph protocols.

4. Relationship Management (Variants and Translations)

AriaML uses a relational logic to link different versions of the same document:

  • workTranslation: Lists existing variants (translations) of the document.
  • translationOfWork: Points to the original work from which the current document originates.

Each relationship entity must include at least an inLanguage and a url property. The engine automatically generates <link rel="alternate" hreflang="..."> tags.

5. Semantic Resolution

If multiple application/ld+json blocks are present, the user agent must perform an additive synthesis. Lists (such as legacyLinks) are accumulated via concatenation, while unique properties (such as name) are resolved in favor of the last declaration encountered in the DOM reading order.

6. Example of a Native AriaML Document

<aria-ml>
    <script type="application/ld+json">
    {
        "@context": ["https://schema.org", "https://ariaml.com/ns/"],
        "@type": "WebPage",
        "@id": "",
        "name": "My AriaML Document Title",
        "inLanguage": "en-US",
        "direction": "ltr",
        "description": "My first AriaML document",
        "csrfToken": "abc-xyz-123-secure-hash",
        "url": "https://domain.com/",
        "author": "https://domain.com/me",
        "license": "https://spdx.org/licenses/MIT",
        "metadatas": {
            "robots": "index, follow, max-image-preview:large"
        },
        "properties": {
            "og:site_name": "My Site",
            "og:locale": "en_US"
        },
        "legacyLinks": [
            { "rel": "me", "href": "https://github.com/user" },
            { "rel": "me", "href": "https://mastodon.social/@user" },
            { "rel": "manifest", "href": "/app.webmanifest"},
            {
                "rel": "search",
                "type": "application/opensearchdescription+xml",
                "title": "Search in this document",
                "href": "/opensearch.xml"
            },
            { "rel": "preconnect", "href": "https://api.domain.com"}
        ]
    }
    </script>
</aria-ml>

Using AriaML Today

1. HTML Backward Compatibility (legacyLinks)

The standard provides a specific property named legacyLinks. It allows the AriaML document to instruct the user agent on how to generate technical and compatibility resources for the HTML <head>. By default, the rel is considered alternate if not specified.

The legacyLinks property is not intended to manage the page's appearance. Resources related to appearance (icons, stylesheets, viewport, theme color) will be handled in a separate, dedicated definition block.

Each object in the list can contain:

  • rel: The relationship (e.g., manifest, me, alternate).
  • sizes: The resource dimensions.
  • type: The MIME type.
  • href: The link to the resource.

2. Integration Example (SSR Polyfill)

In SSR mode, the server extracts data from the JSON-LD block to pre-fill the HTML <head>. The data-ssr attribute on the <head> tag tells the standalone.js script not to re-execute the initial node creation to optimize performance.

<!DOCTYPE html>
<html dir="ltr" lang="en-US">
<head data-ssr>
    <meta charset="utf-8">
    <title>My AriaML Document Title</title>
    <meta name="description" content="My first AriaML document">
    <meta name="csrf-token" content="abc-xyz-123-secure-hash">
    <link rel="canonical" href="https://domain.com/">
    <link rel="author" href="https://domain.com/me">
    <link rel="license" href="https://spdx.org/licenses/MIT">

    <meta name="robots" content="index, follow, max-image-preview:large">
    <meta property="og:site_name" content="My Site">
    <meta property="og:locale" content="en_US">

    <link rel="me" href="https://github.com/user">
    <link rel="me" href="https://mastodon.social/@user">
    <link rel="manifest" href="/app.webmanifest">
    <link rel="search" type="application/opensearchdescription+xml" title="Search in this document" href="/opensearch.xml">
    <link rel="preconnect" href="https://api.domain.com">
</head>
<body>
    <aria-ml>
        <script type="application/ld+json">
            /* ... JSON content identical to the section 6 example ... */
        </script>
    </aria-ml>
    <script src="aria-ml/standalone.js"></script>
</body>
</html>

Next Fluid Navigation