Définition d'un Document

Définition et Structure d'un document AriaML

Structure d'un document AriaML

Le standard AriaML définit un format de document structuré, identifiable et interopérable. Il est conçu pour être interprété nativement par les navigateurs ou les liseuses, qu'ils soient consultés sur le web, ouverts comme fichiers locaux, ou exécutés en tant qu'applications (PWA).

Un document AriaML n'a ni doctype ni balise html, head ou body.
Il n'existe qu'en UTF8.
Il est embarqué intégralement dans une balise aria-ml.
Il hérite de html et peut contenir les même éléments que body. Ainsi que quelques éléments supplémentaires

Voici à quoi un document AriaML ressemble:

<aria-ml nav-base-url="/">  
    <script type="application/ld+json" nav-slot="dynamic-def">{
        "name": "Page Produit",
        "inLanguage": "fr-FR",
        "direction": "ltr",
        "csrfToken": "token-123"
    }</script>

    <g id="static">
        <script type="application/ld+json">{
            "url": "https://monsite.com/chaussures",
            "@context": [
                "https://schema.org",
                "https://ariaml.com/ns/"
            ],
            "@type": "WebPage",
            "properties": {
                "og:type": "product",
                "og:image": "/assets/shoes.jpg"
            },
            "metadatas": {
                "robots": "index, follow"
            }
        }</script>

        <style src="/css/style.css" preload>@import url("/css/style.css");</style>
        <style src="/css/dark.css" theme="dark" preload media-theme="(prefers-color-scheme: dark)"></style>
        <style src="/css/light.css" theme="light" preload media-theme="(prefers-color-scheme: light)"></style>
    </g>

    <g nav-slot="dynamic-styles">

    <style src="/css/icons.json" type="icons+json" preload></style>
    <style>h1 {color: red;}</style>    </g>

    <main nav-slot="content">
            <div nav-cache="main-view">
                <h1>Hello Word!</h1>
                <p>This is my first AriaML Document</p>
            </div>
    </main>

</aria-ml>

Rétro compatibilité : Un navigateur ou un moteur de recherche non compatible avec le format AriaML pourra recevoir le document AriaML imbriqué dans un document HTML et supporté par un polyfill écrit en Javascript disponible ici.

<!DOCTYPE html>
<html lang="fr-FR" dir="ltr">
<head data-ssr>
    <meta charset="utf-8">
    <title>Page Produit</title>
    <link rel="canonical" href="https://monsite.com/chaussures">
    <meta name="csrf-token" content="token-123">
    <meta name="robots" content="index, follow">
    <meta property="og:type" content="product">
    <meta property="og:image" content="/assets/shoes.jpg">
    <link rel="preload" href="/css/style.css" as="style">
    <link rel="preload" href="/css/dark.css" as="style">
    <link rel="preload" href="/css/light.css" as="style">
    <link rel="preload" href="/css/icons.json" as="style">
</head>
<body>
<aria-ml nav-base-url="/">
    <!-- CONTENU IDENTIQUE A L'EXEMPLE PRÉCÉDENT -->
</aria-ml>
<script src="https://flavi1.github.io/aria-ml/src/standalone.js"></script>
</body>
</html>

Un helper en PHP est disponible pour vous aider à gérer le rendu côté serveur (SSR). Vous trouverez toutes les informations necessaires pour implémenter le rendu SSR dans un autre langage ici.

1. Déclaration du Contexte et Espace de Noms

Les propriétés d'un document AriaML peuvent être déclarées via l'utilisation d'un double contexte sémantique. Le contexte AriaML étend les capacités de Schema.org pour offrir une précision accrue sur les métadonnées de contrôle.

{
    "@context": [
        "[https://schema.org](https://schema.org)",
        "[https://ariaml.com/ns/](https://ariaml.com/ns/)"
    ]
}

Priorité : En cas de conflit de propriétés, l'espace de noms https://ariaml.com/ns prévaut sur le vocabulaire généraliste.

2. Types de Documents Autorisés

Pour être valide, la description du document racine doit utiliser l'un des types suivants, définissant l'intention d'usage de l'objet :

Article : Contenu éditorial ou textuel prédominant.
WebPage : Document exposé sur un réseau public.
DigitalDocument : Fichier autonome, souvent utilisé pour les documents locaux ou éditables.
SoftwareApplication : Document servant d'interface à une application ou une PWA.

3. Identité et Propriétés Fondamentales

L'identité globale du document est définie par le bloc dont l'identifiant (@id) est soit absent, soit défini par une chaîne vide ("") ou le caractère #.

Mappage des propriétés système :

L'agent utilisateur doit mapper les propriétés JSON-LD suivantes aux composants natifs de l'interface :

Propriété AriaML	Composant Système / UI	Description
`name`	Titre du Document	Définit le nom affiché dans l'onglet ou la barre de titre.
`description`	Description du Document	Description du contenu (équivalent de la balise meta description).
`inLanguage`	Attribut de Langue	Définit la langue pour la synthèse vocale et le rendu.
`direction`	Sens de lecture	Définit l'orientation du flux (ex: `ltr`, `rtl`).
`url`	Identifiant Canonique	L'URL d'autorité du document (rel="canonical").
`author`	Auteur	Lien vers l'identité de l'auteur (rel="author").
`license`	Licence	Lien vers les conditions d'utilisation (rel="license").
`csrfToken`	Sécurité	Jeton de sécurité pour les mutations (meta name="csrf-token").

Les metadatas sont les équivalents de la balise <meta name="...">. L'objet JSON associe une clé (attribut name) à une valeur (attribut content). La liste properties correspond aux balises <meta property="...">, principalement utilisées pour les protocoles Open Graph.

4. Gestion des Relations (Variantes et Traductions)

AriaML utilise une logique relationnelle pour lier les différentes versions d'un même document :

workTranslation : Liste les variantes (traductions) existantes du document.
translationOfWork : Désigne l'œuvre originale dont le document actuel est issu.

Chaque entité de relation doit au minimum comporter une propriété inLanguage et une url. Le moteur génère automatiquement les balises <link rel="alternate" hreflang="...">.

5. Résolution Sémantique

Si plusieurs blocs application/ld+json sont présents, l'agent utilisateur doit effectuer une synthèse additive. Les listes (comme legacyLinks) sont cumulées par concaténation, tandis que les propriétés uniques (comme name) sont résolues en faveur de la dernière déclaration rencontrée dans l'ordre de lecture du DOM.

6. Exemple d'un document AriaML natif

<aria-ml>
**Suite** [Navigation Fluide](/fr/navigation)
    <script type="application/ld+json">
    {
        "@context": ["[https://schema.org](https://schema.org)", "[https://ariaml.com/ns/](https://ariaml.com/ns/)"],
        "@type": "WebPage",
        "@id": "",
        "name": "Titre de mon document AriaML",
        "inLanguage": "fr-FR",
        "direction": "ltr",
        "description": "Mon premier document AriaML",
        "csrfToken": "abc-xyz-123-secure-hash",
        "url": "[https://domain.com/](https://domain.com/)",
        "author": "[https://domain.com/me](https://domain.com/me)",
        "license": "[https://spdx.org/licenses/MIT](https://spdx.org/licenses/MIT)",
        "metadatas": {
            "robots": "index, follow, max-image-preview:large"
        },
        "properties": {
            "og:site_name": "Mon site",
            "og:locale": "fr_FR"
        },
        "legacyLinks": [
            { "rel": "me", "href": "[https://github.com/user](https://github.com/user)" },
            { "rel": "me", "href": "[https://mastodon.social/@user](https://mastodon.social/@user)" },
            { "rel": "manifest", "href": "/app.webmanifest"},
            {
                "rel": "search",
                "type": "application/opensearchdescription+xml",
                "title": "Rechercher dans ce document",
                "href": "/opensearch.xml"
            },
            { "rel": "preconnect", "href": "[https://api.domain.com](https://api.domain.com)"}
        ]
    }
    </script>
</aria-ml>

Utiliser AriaML dès aujourd'hui

1. Rétrocompatibilité HTML (legacyLinks)

Le standard prévoit une propriété spécifique nommée legacyLinks. Elle permet au document AriaML d'indiquer à l'agent utilisateur comment générer des ressources techniques et de compatibilité pour le <head> HTML. Par défaut, le rel est considéré comme alternate s'il n'est pas précisé. La propriété legacyLinks n'est pas destinée à gérer l'apparence de la page. Les ressources liées à l'apparence (icones, stylesheets, viewport, theme color) seront traités dans un autre bloc de définition dédié.

Chaque objet de la liste peut contenir :

rel : La relation (ex: manifest, me, alternate).
sizes : Les dimensions de la ressource.
type : Le type MIME.
href : Le lien vers la ressource.

2. Exemple d'intégration (Polyfill SSR)

En mode SSR, le serveur extrait les données du bloc JSON-LD pour pré-remplir le <head> HTML. L'attribut data-ssr sur la balise <head> indique au script standalone.js de ne pas ré-exécuter la création initiale des nœuds pour optimiser les performances.

<!DOCTYPE html>
<html dir="ltr" lang="fr-FR">
<head data-ssr>
    <meta charset="utf-8">
    <title>Titre de mon document AriaML</title>
    <meta name="description" content="Mon premier document AriaML">
    <meta name="csrf-token" content="abc-xyz-123-secure-hash">
    <link rel="canonical" href="[https://domain.com/](https://domain.com/)">
    <link rel="author" href="[https://domain.com/me](https://domain.com/me)">
    <link rel="license" href="[https://spdx.org/licenses/MIT](https://spdx.org/licenses/MIT)">

    <meta name="robots" content="index, follow, max-image-preview:large">
    <meta property="og:site_name" content="Mon site">
    <meta property="og:locale" content="fr_FR">

    <link rel="me" href="[https://github.com/user](https://github.com/user)">
    <link rel="me" href="[https://mastodon.social/@user](https://mastodon.social/@user)">
    <link rel="manifest" href="/app.webmanifest">
    <link rel="search" type="application/opensearchdescription+xml" title="Rechercher dans ce document" href="/opensearch.xml">
    <link rel="preconnect" href="[https://api.domain.com](https://api.domain.com)">
</head>
<body>
    <aria-ml>
        <script type="application/ld+json">
            /* ... Contenu JSON identique à l'exemple section 6 ... */
        </script>
    </aria-ml>
    <script src="aria-ml/standalone.js"></script>
</body>
</html>

Suite Navigation Fluide

Aria Markup Language