Flux de base
- L’agent écrit un paquet source .owx.
ow a2ui checkvalide le contrat de création fermé.ow a2ui compileémet l’artefact JSON typé Render Document.ow publishenvoie l’artefact validé vers OWL Compose Hosted.
OWX est la source de création. Le JSON compilé est une sortie, pas un second langage de création. Le XML non pris en charge, le HTML arbitraire, JavaScript, le Markdown brut et les fichiers compilés modifiés à la main sont hors contrat.
Tutoriel
Créez un document OWX étape par étape.
Ce tutoriel commence par un document minimal, ajoute des données, des requêtes, des faits et des composants d’affichage, puis exécute les commandes de validation, de compilation et de publication. Consultez le tableau des nœuds et le contrat machine à la fin pour une référence exacte.
1. Commencer par la structure du document
Chaque œuvre possède une seule racine ow-document. Déclarez la version exacte du protocole et les métadonnées, puis placez le contenu destiné aux lecteurs dans des sections et des nœuds typés.
<ow-document owx-version="1" title="Decision brief" canvas="briefing">
<section id="overview">
<ow-text id="summary" title="Decision brief" title-level="1" body="A concise conclusion." />
</section>
</ow-document>Le title de la racine est une métadonnée. Un titre visible doit être un enfant ow-text explicite ; ne répétez pas le même titre dans du texte libre.
2. Ajouter données, requêtes et faits
Gardez les éléments probants typés et reproductibles. Chargez un dataset, transformez-le avec une requête et exposez avec un fact la valeur exacte qu’un composant doit afficher.
<ow-document owx-version="1" title="Regional revenue">
<ow-data id="sales" src="./sales.csv" schema="./sales.toml" />
<ow-query id="sales-by-region" from="dataset:sales">
<ow-group by="region" />
<ow-aggregate name="revenue" operation="sum" field="revenue" />
</ow-query>
<ow-fact id="total-revenue" query="query:sales-by-region" field="revenue" />
</ow-document>Les queries décrivent les transformations ; les facts nomment les valeurs consommées par les nœuds de présentation. Ne modifiez pas le JSON compilé à la main pour changer un nombre.
3. Placer les composants pris en charge
Composez la vue du lecteur avec des nœuds de mise en page et de présentation typés. Reliez métriques, graphiques et tableaux à une requête ou un fait vérifié au lieu de répéter les mêmes affirmations en prose.
<section id="summary">
<ow-grid id="cards">
<ow-metric id="revenue" fact="fact:total-revenue" label="Revenue" />
<ow-chart id="revenue-chart" data="query:sales-by-region" type="bar" title="Revenue by region" summary="Compare revenue by region." />
<ow-table id="regional-table" data="query:sales-by-region" title="By region" />
</ow-grid>
</section>Choisissez le composant selon la question du lecteur. Un graphique, un tableau, une carte ou un graphe n’est utile que si son lien de données et son rôle visuel sont explicites.
4. Valider, compiler et publier
Le paquet source est la source de travail. Exécutez les contrôles dans l’ordre, inspectez le résultat compilé et ne publiez que l’artefact JSON Render Document validé.
ow a2ui check ./artifact/document.owx
ow a2ui fmt ./artifact/document.owx
ow a2ui compile ./artifact/document.owx --output ./artifact/document.json
ow a2ui digest ./artifact/document.json
ow publish ./artifact/document.json --no-open`check` détecte la syntaxe, les types, les bindings, l’appartenance au catalog et les limites de ressources. `compile` crée l’artefact, `digest` enregistre son identité exacte et `publish` l’envoie à Hosted.
Nœuds courants en un coup d’œil
Voici les nœuds qu’un agent utilise le plus souvent. Chaque signature montre les attributs qui l’identifient généralement ; consultez le catalog généré pour les champs optionnels et les relations d’enfants.
Structure du document
Commencez par la racine et donnez un parent réel à chaque région visible.
| Balise | Signature | Utilité |
|---|---|---|
ow-document | <ow-document owx-version title> | La racine d’auteur unique et la limite du protocole. |
section | <section id> | Une région sémantique avec un id stable. |
ow-text | <ow-text id title title-level> | Titre, surtitre, corps ou références de faits visibles. |
ow-grid | <ow-grid id class> | Conteneur de mise en page responsive pour enfants typés. |
Données et éléments probants
Rendez vérifiable le chemin entre la source et la valeur affichée.
| Balise | Signature | Utilité |
|---|---|---|
ow-data | <ow-data id src schema> | Dataset typé chargé depuis une source locale au paquet. |
ow-query | <ow-query id from> | Pipeline reproductible de filtres, dérivations, groupes ou agrégations. |
ow-fact | <ow-fact id query field> | Valeur nommée résolue depuis une requête et un champ. |
ow-sources | <ow-sources src> | Registre des sources associé à l’œuvre. |
Présentation
Utilisez une visualisation typée lorsqu’elle répond à une question précise.
| Balise | Signature | Utilité |
|---|---|---|
ow-metric | <ow-metric id fact label> | Valeur mise en avant et liée à un fait. |
ow-chart | <ow-chart id data type title summary> | Graphique lié à une requête avec un type explicite. |
ow-table | <ow-table id data> | Vue tabulaire d’un dataset ou d’une requête vérifiés. |
ow-map | <ow-map id data place country level join value title summary> | Vue géographique avec champs de lieu et de valeur. |
Relations et interaction
Déclarez la topologie et un état borné plutôt que du HTML arbitraire.
| Balise | Signature | Utilité |
|---|---|---|
ow-graph | <ow-graph id layout direction> | Conteneur de graphe conscient de la topologie. |
ow-graph-node | <ow-graph-node id label> | Nœud étiqueté dans un ow-graph. |
ow-connector | <ow-connector from to> | Relation typée entre des extrémités connues. |
ow-view-switcher | <ow-view-switcher id label> | Ensemble borné de vues nommées. |
Contenu de soutien
Utilisez des médias locaux au paquet et des blocs auxiliaires explicites.
| Balise | Signature | Utilité |
|---|---|---|
ow-media | <ow-media id file alt> | Image locale au paquet avec un texte alt pertinent. |
ow-code | <ow-code id language value> | Bloc de code dont le langage est explicite. |
ow-list | <ow-list id> | Liste typée ordonnée ou non ordonnée. |
ow-callout | <ow-callout id title body> | Note ou encadré de décision avec étiquette. |
Règles pour garder un résultat sûr
- Le catalog d’auteur est fermé : une balise ou un attribut ow-* non enregistré n’est pas un composant de secours.
- Conservez une seule source .owx. Le JSON compilé est un artefact généré, pas un second langage d’auteur.
- Reliez les faits externes avec des données, requêtes et facts typés ; n’inventez pas de valeurs pour remplir la mise en page.
- Utilisez seulement des médias locaux au paquet et des classes prises en charge. HTML arbitraire, JavaScript, ressources distantes et traversée de chemin échouent fermement.
Parcours OWX pris en charge
Guide du contrat machine et de l’audit
Le tutoriel ci-dessus est l’entrée normale. Les liens suivants renvoient au parcours pris en charge, au tableau des nœuds de cette page et aux guides maintenus de la CLI et de création, pour vérifier les noms, attributs, relations ou versions.
Ce qu’une personne doit voir
Le parcours destiné à l’auteur doit montrer l’objectif, les matériaux, les limites des sources, le résultat de la validation, un aperçu réel et l’action en attente d’approbation. L’OWX brut est une surface d’audit, pas l’expérience de lecture par défaut. Le propriétaire peut inspecter le paquet source et le digest exact lorsqu’il faut vérifier la provenance ou déboguer.
Vous découvrez OWL Compose ?
Commencez avec votre agent.
Commencez par comprendre le parcours du produit. Revenez ici uniquement lorsque l’agent ou un auditeur a besoin du contrat sous-jacent.