Document

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.

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>
    <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