Diagramme de structure d'entités

À propos des diagrammes de structure d'entités

Un diagramme de structure d'entités cartographie les relations juridiques et économiques entre organisations et personnes — qui possède quoi, à travers quelle forme d'entité et dans quelle juridiction. Les avocats d'affaires les utilisent pour documenter les structures de holding et les chaînes de filiales. Les conseillers fiscaux les dessinent pour montrer les flux de licences de propriété intellectuelle transfrontaliers et les dispositifs de prix de transfert. Les avocats de startups les produisent pour les tableaux de capitalisation et les consentements des conseils d'administration. Les planificateurs successoraux les utilisent pour montrer les arrangements cédant-trust-bénéficiaire. Le diagramme est le premier document demandé dans tout processus de diligence raisonnable M&A et la pièce jointe standard à un fichier maître de prix de transfert OCDE.

Schematex suit les conventions de praticiens synthétisées à partir de l'article 21 du Règlement S-K de la SEC (divulgation des filiales), des classifications d'entités IRS Form 8832, des codes de juridiction ISO 3166-1, des formes d'entités juridiques ISO 20275 et des conventions de mémos fiscaux des Big Four. Les types d'entités correspondent à des formes distinctes (rectangle pour une société, rectangle arrondi pour une LLC, ellipse pour un trust) afin que tout lecteur puisse identifier la forme juridique en un coup d'œil. Cette page documente ce que l'analyseur accepte aujourd'hui.

1. Votre première structure d'entités

La structure d'entités utile minimale : une société mère détenant deux filiales.

Quatre règles couvrent 80 % de l'usage :

1. Commencez par entity-structure, optionnellement suivi d'un titre entre guillemets.
2. Chaque entité juridique est un nœud : entity ID "Nom d'affichage" type — le type détermine la forme.
3. Connectez les entités avec ->. Ajoutez : pct pour étiqueter le pourcentage de détention : parent -> child : 60%.
4. Ajoutez @juridiction après le type pour afficher un badge de juridiction : corp@DE.

Les commentaires doivent commencer par # sur leur propre ligne.

2. Types d'entités

Le type d'entité détermine la forme rendue pour ce nœud. Schematex mappe plusieurs alias courants vers un type canonique.

Syntaxe d'entité :

entity ID "Nom d'affichage" type
entity ID "Nom d'affichage" type@JURIDICTION
entity ID "Nom d'affichage" type@JURIDICTION [propriétés]

Règles d'identifiant. Doit commencer par une lettre, suivie de lettres, chiffres, underscores ou tirets : [A-Za-z][A-Za-z0-9_-]*.

3. Propriétés de nœud

Les propriétés optionnelles dans […] annotent l'entité avec du contexte supplémentaire visible dans le nœud rendu.

Toute clé ne figurant pas dans l'ensemble réservé (status, tax, role, note, est) est stockée comme propriété personnalisée.

entity alice "Alice Chen" individual [role: "Founder & CEO"]
entity trust1 "Smith Irrevocable Trust" trust@SD [est: "2019-06-01", note: "Spendthrift provisions"]
entity opco "OpCo, Inc." corp@DE [status: new, tax: ccorp]

4. Juridiction

Ajoutez @CODE après le type d'entité pour afficher un badge de juridiction sur le nœud. Le code est une chaîne de 2 à 3 lettres — les codes pays alpha-2 ISO 3166-1 et les abréviations d'États américains sont tous deux acceptés.

entity parent "Parent Corp" corp@US
entity ie_sub "Ireland Sub" corp@IE
entity ky_fund "Cayman Fund" lp@KY
entity de_llc "Delaware LLC" llc@DE

Codes courants : US États-Unis · DE Delaware · CA Californie · NY New York · UK Royaume-Uni · IE Irlande · NL Pays-Bas · KY Îles Caïmans · SG Singapour · HK Hong Kong · JP Japon · BM Bermudes · VG Îles Vierges britanniques · CH Suisse · LU Luxembourg · SD Dakota du Sud.

@DE se résout comme Delaware par défaut (le plus courant dans les contextes juridiques américains).

Clusters de juridiction

Déclarez une juridiction avec jurisdiction CODE "Nom" [color: "#hex"] pour regrouper toutes les entités partageant ce code dans une région de cluster à bordure en pointillé étiquetée sur le diagramme.

jurisdiction US "United States" [color: "#3b82f6"]
jurisdiction IE "Ireland" [color: "#059669"]

Lorsque le @CODE d'une entité correspond à une jurisdiction déclarée, elle est automatiquement placée à l'intérieur de ce cluster. Si jurisdiction n'est pas déclaré, le badge apparaît quand même mais aucune région de cluster n'est dessinée.

Clusters manuels

Utilisez cluster "Étiquette" [members: [id1, id2], color: "#hex"] pour regrouper des entités qui ne partagent pas un seul code de juridiction.

cluster "Ireland / Cayman IP" [members: [ie_ip, nl_bv], color: "#059669"]

5. Arêtes de détention

Une ligne d'arête connecte deux identifiants d'entité avec un opérateur. L'opérateur détermine le style de ligne et la sémantique visuelle.

Pourcentage de détention : ajoutez : pct après l'identifiant cible.

parent -> subsidiary : 60%

Catégorie d'actions : ajoutez [class: "Série A Pref"] pour étiqueter la catégorie d'actions sur l'arête.

vc -> startup : 22% [class: "Series A Pref"]

Étiquette non-capital : utilisez [label: "…"] pour du texte d'arête descriptif sur les arêtes de licence ou de distribution.

ip_co -~-> opco [label: "IP License · royalty"]
trust --> beneficiary [label: "Discretionary distributions"]

Combinaison : class: et label: peuvent apparaître ensemble.

fund -> portfolio : 35% [class: "Common", label: "Post-Series B"]

6. Étiquettes et commentaires

• Titre : entity-structure "Acme Holdings" — première ligne, entre guillemets.
• Nom d'affichage de l'entité : la chaîne entre guillemets dans entity ID "Nom" type — apparaît à l'intérieur du nœud.
• Badge de juridiction : @CODE après le type — code de 2 à 3 lettres affiché dans le coin du nœud.
• Propriétés de nœud : [note: "…", role: "…", status: new, …] — annotations à l'intérieur du nœud.
• Pourcentage d'arête : : pct après l'identifiant cible — apparaît sur la flèche de détention.
• Catégorie d'arête : [class: "…"] — étiquette de catégorie d'actions sur la flèche.
• Étiquette d'arête : [label: "…"] — texte descriptif sur la flèche.
• Commentaires : # au début d'une ligne (après les espaces initiaux). Les commentaires en fin de ligne # à l'intérieur des blocs entre crochets sont également supprimés.

7. Mots réservés et échappement

Réservés en début de ligne : entity-structure (en-tête), entity, jurisdiction, cluster.

Mots-clés de type d'entité — ces chaînes sont analysées comme des types d'entités et ne doivent pas être utilisées comme identifiants d'entités : corp, corporation, inc, llc, llp, gmbh, bv, lp, lllp, fund, trust, individual, person, foundation, npo, disregarded, branch, pool, placeholder, tbf.

Jetons d'opérateurs d'arêtes — évitez ces séquences dans les identifiants : ->, ==>, -.->, -~->, -->.

Les chaînes avec des espaces doivent être entre double guillemets dans les noms d'affichage, les notes, les étiquettes de rôle et les valeurs de couleur.

Les codes de juridiction sont insensibles à la casse dans la source mais normalisés en majuscules : @de et @DE sont équivalents.

8. Erreurs courantes

9. Grammaire (EBNF)

document        = header (blank | comment | jurisdiction-def | cluster-def | entity-def | edge)*

header          = "entity-structure" ( WS quoted-string )? NEWLINE
quoted-string   = '"' any-char-but-quote* '"'

jurisdiction-def = "jurisdiction" CODE WS quoted-string ( "[" jur-attrs "]" )? NEWLINE
jur-attrs        = jur-attr ("," jur-attr)*
jur-attr         = "color:" quoted-string

cluster-def     = "cluster" WS quoted-string ( "[" cluster-attrs "]" )? NEWLINE
cluster-attrs   = cluster-attr ("," cluster-attr)*
cluster-attr    = "members:" "[" id ("," id)* "]"
                | "color:" quoted-string

entity-def      = "entity" WS id WS quoted-string WS entity-type ( "@" CODE )?
                  ( "[" entity-attrs "]" )? NEWLINE
entity-attrs    = entity-attr ("," entity-attr)*
entity-attr     = "status:" status
                | "tax:" quoted-string
                | "role:" quoted-string
                | "note:" quoted-string
                | "est:" quoted-string
                | key ":" quoted-string        # propriété personnalisée

entity-type     = "corp" | "corporation" | "inc"
                | "llc" | "llp" | "gmbh" | "bv"
                | "lp" | "lllp" | "fund"
                | "trust"
                | "individual" | "person"
                | "foundation" | "npo"
                | "disregarded" | "branch"
                | "pool"
                | "placeholder" | "tbf"

edge            = id WS op WS id ( ":" WS pct-text )? ( "[" edge-attrs "]" )? NEWLINE
op              = "->" | "==>" | "-.->" | "-~->" | "-->"
pct-text        = tout texte jusqu'à "[" ou fin de ligne   # ex. "100%" ou "V 75% / E 50%"

edge-attrs      = edge-attr ("," edge-attr)*
edge-attr       = "class:" quoted-string
                | "label:" quoted-string

status          = "new" | "eliminated" | "modified" | "normal"
CODE            = [A-Za-z]{2,3}
id              = [A-Za-z] [A-Za-z0-9_-]*
comment         = "#" any NEWLINE

Source faisant autorité : src/diagrams/entity/parser.ts. En cas de divergence avec l'analyseur, l'analyseur l'emporte — veuillez ouvrir un ticket.

10. Conformité aux normes

Les diagrammes de structure d'entités Schematex synthétisent les conventions issues de :

• SEC Regulation S-K, Item 601(b)(21) — conventions de divulgation des filiales selon l'Annexe 21
• IRS Form 8832 — classifications d'entités C-corp / pass-through / transparente
• ISO 3166-1 alpha-2 — codes de juridiction sur les badges de nœuds
• ISO 20275:2017 — classification des formes d'entités selon l'identifiant d'entité juridique (LEI)
• Directives OCDE sur les prix de transfert (2022) — conventions de flux de licences de PI et de redevances transfrontaliers
• Conventions de mémos fiscaux des Big Four (EY / PwC / KPMG / Deloitte) — norme de facto pour les diagrammes de structures transfrontalières

Ce qui est implémenté aujourd'hui :

• ✅ Neuf types d'entités avec des formes distinctes : corp, llc, lp, trust, individual, foundation, disregarded, pool, placeholder
• ✅ Alias de type : corporation, inc, llp, gmbh, bv, lllp, fund, person, npo, branch, tbf
• ✅ Cinq opérateurs d'arête : -> (détention), ==> (vote), -.-> (pool), -~-> (licence), --> (distribution)
• ✅ Étiquettes de pourcentage de détention (: pct) et catégorie d'actions ([class: "…"])
• ✅ Badges de juridiction (@CODE) avec codes ISO 3166-1 et d'États américains
• ✅ Régions de clusters de juridiction (regroupement à bordure en pointillé par @CODE)
• ✅ Clusters manuels (cluster "…" [members: […]])
• ✅ Propriétés de nœud : status, tax, role, note, est, paires clé-valeur personnalisées
• ⏳ Pourcentage fractionné V/E — V 75% / E 50% stocké dans la chaîne percentage mais le rendu sous forme d'étiquette à deux lignes n'est pas encore implémenté
• ⏳ Rendu de diff par étape de transaction — status: new / eliminated / modified stocké mais les badges de diff visuels ne sont pas encore rendus
• ⏳ Annotation du nombre d'actions en ligne — 100 shares Common aux côtés du pourcentage

11. Exemples associés

12. Feuille de route

Prévu — pas encore analysable. Ne l'utilisez pas dans le DSL généré aujourd'hui ; l'analyseur le rejettera ou l'ignorera.

• Rendu de pourcentage fractionné V/E — V 75% / E 50% sur une seule arête, affiché comme une étiquette de pourcentage à deux lignes distinguant l'intérêt de vote de l'intérêt économique.
• Badges de diff par étape de transaction — status: new rend un badge vert « NEW » ; status: eliminated rend un texte barré rouge ; utilisé pour la comparaison de structures avant/après M&A sur un seul diagramme.
• Annotation du nombre d'actions — -> sub : 100 shares Common aux côtés d'un pourcentage pour capturer le nombre exact d'actions d'un tableau de capitalisation.
• Détention bidirectionnelle — arête <-> explicite pour la détention croisée (deux entités se détenant mutuellement), avec routage en courbe S pour éviter l'encombrement.
• Bloc de légende — légende auto-générée montrant la correspondance forme-type d'entité et opérateur-type de relation.

Suivez dans les tickets GitHub si vous avez besoin de l'une de ces fonctionnalités plus tôt.