Manifeste et configuration

Resource Extension

Le manifeste suit une enveloppe stable :

apiVersion: ormuz.io/v1alpha1
kind: Extension
metadata:
  name: acme_pay
  title: Acme Pay
spec:
  version: 1.0.0
  platformApiVersion: "1"
  defaultLocale: en-US
  supportedLocales:
    - en-US
    - fr-FR
  runtime:
    api: ./api/index.cjs
  extensionKind: provider_integration
  cardinality: multi
  activation:
    when: on_connection_test
  capabilities:
    - payment_processing
  integrationMechanisms:
    - rest_api
  channels: []
  contributes:
    nodes: []
    tools: []

apiVersion, kind, metadata.name et les champs obligatoires de spec sont validés avant que le package puisse être chargé. Les projections runtime du manifeste sont générées depuis cette source ; elles ne constituent pas des fichiers éditables concurrents.

Identité et namespaces

metadata.name est l’identifiant stable de l’extension. Il utilise le lowercase snake_case, commence par une lettre et doit être unique dans la plateforme.

Cette identité porte aussi le namespace des contributions. Par exemple, l’extension stripe peut contribuer stripe.ensure_customer. Le namespace ormuz est réservé aux exécutables Core et ne peut pas être utilisé comme identifiant d’extension.

Les identifiants techniques ne doivent pas être renommés pour des raisons de présentation. Utilisez metadata.title et les ressources localisées pour les labels destinés aux utilisateurs.

Contrat déclaratif

La cardinalité décrit le nombre de configurations qu’un marchand peut créer. Utilisez singleton lorsqu’une seule configuration a un sens dans un périmètre marchand et multi lorsque plusieurs connexions distinctes doivent pouvoir coexister.

L’activation décrit la condition d’entrée en service. Elle ne représente ni un niveau de certification, ni un statut commercial, ni une permission de données.

Contrats runtime et configuration

Tout contrat public d’une extension n’est pas nécessairement sérialisé dans extension.yaml. Le manifeste contient les faits structurels du package ; les contrats qui nécessitent du code restent attachés au runtime approprié.

Le configSchema décrit les valeurs spécifiques à l’installation du marchand. Les secrets fournis par le marchand y sont déclarés comme secret et ne doivent jamais être recopiés dans les métadonnées publiques du manifeste.

• une configuration demande uniquement les valeurs nécessaires aux channels et capacités activées ;
• les secrets émis par Ormuz ne sont pas modélisés comme des champs fournis par le marchand ;
• un champ référencé par un channel doit être compatible avec son usage, par exemple une URL pour une cible event_out ;
• les fonctions d’exécution, de validation, de normalisation et les clients provider restent du comportement runtime, jamais du YAML déclaratif.

Métadonnées de découverte

Les métadonnées spec.marketplace servent à présenter l’extension et ses prérequis. Elles ne changent ni son autorité ni son comportement runtime.

Le contrat actuel distingue notamment un statut de disponibilité (available, beta, coming_soon), une estimation de mise en place, la disponibilité d’un sandbox, l’éditeur, les points forts, cas d’usage, prérequis et ressources documentaires.

Règles de conception

• Éditez extension.yaml, pas ses projections générées.
• Déclarez la réalité actuelle, pas la roadmap.
• Ne dupliquez pas une capacité uniquement pour améliorer le marketing de la fiche.
• Une capability n’est pas une permission et ne crée aucun accès implicite.
• Une nouvelle contribution doit entrer dans les validations du contrat avant d’être documentée comme supportée.
• Après une modification structurelle, régénérez les projections puis exécutez le preflight.