mde-abox

name

mde-abox

description

Convention for generating ABox (instance data) files inside an MDE project. Use when extracting instance triples from a source document (analyses, requirements, mapping tables) into `ontology/ABox/`: produces a `.ttl` with concrete instances conforming to a referenced TBox plus a `.md` companion with description + runnable PowerShell load + sample SPARQL query. Triggers on "extract instances", "generate ABox", "create RDF data from doc", "populate ontology with examples", "instance data for ontology".

ABox generation convention

Convenzione per generare file di dati istanziati (ABox = Assertional Box) in un progetto MDE configurato per Apache Jena Fuseki. Si applica quando un AI agent estrae istanze concrete da un documento sorgente (analisi tecnica, requirement, tabella di mapping, conversazione) e le materializza come triple RDF conformi a una TBox preesistente.

Cosa è una ABox

La ABox contiene i dati: istanze concrete di classi definite nella TBox. Esempio: se la TBox dichiara stem:EntityStem come classe, una ABox conterrà <urn:mde:abox:...:CNT> a stem:EntityStem ; stem:stemId "CNT" ; ....

La ABox cresce continuamente con il progredire dell'analisi e va aggiornata in modo idempotente per ogni documento sorgente.

Prerequisito

La TBox di riferimento deve già essere caricata sul dataset Fuseki target. Senza, il triplestore accetta comunque le triple ma non può ragionare su classi/proprietà. Verifica con SPARQL ASK { ?c a owl:Class } prima di generare la ABox.

Se la TBox non c'è, fermarsi e chiedere all'utente di caricarla via ontology/TBox/load-all.md (vedi [[mde-tbox]]).

Layout obbligatorio dei file

ontology/ABox/<dataset-name>.ttl    ← Turtle con le istanze
ontology/ABox/<dataset-name>.md     ← descrizione + runnable di caricamento + sample query

<dataset-name> è kebab-case, descrittivo, identifica il set di istanze che il file contiene. Esempi: example-stems, CWPGFG10-analysis, payment-domain-data, raiffeisen-poc-instances.

Struttura del file .ttl

1. Header di commento

# ============================================================
#  <dataset-name>.ttl
#  <Descrizione di cosa rappresentano queste istanze>
#  Conformante a TBox: <lista dei layer TBox usati>
# ============================================================

2. Prefissi: TBox + namespace locale

Importare i prefissi TBox che si useranno (uno o più dei https://<authority>/ontology/<domain>/<package>#) e definire un namespace locale per le istanze:

@prefix stem: <https://dedagroup.it/ontology/cobol2java/stem#> .
@prefix call: <https://dedagroup.it/ontology/cobol2java/cobol/callable#> .
@prefix :     <urn:mde:abox:<dataset-name>#> .

Il namespace vuoto (@prefix : <urn:mde:abox:...#> .) è convenzione per le istanze locali al file. :CNT diventa <urn:mde:abox:<dataset-name>#CNT>. Pulito e tracciabile.

3. Istanze tipizzate

Ogni istanza deve dichiarare la classe TBox di appartenenza con a (alias di rdf:type):

:CNT  a  stem:EntityStem ;
    stem:stemId        "CNT" ;
    stem:canonicalName "Contatore" ;
    stem:usageCount    47 ;
    stem:keyRole       "PK_CANDIDATE" .

4. Letterali tipati XSD

Usare il tipo esplicito quando ha senso:

:binding001  a  tb:TransformationBinding ;
    tb:multiplicity  "ONE_TO_ONE" ;
    tb:generatedAt   "2026-05-26T14:30:00Z"^^xsd:dateTime ;
    tb:justification "Mapping diretto, nessuna decomposizione necessaria"@it .

• Stringhe in italiano: "..."@it
• Stringhe in inglese: "..."@en (se rilevante)
• Interi: senza virgolette (47, non "47") — Turtle inferisce xsd:integer
• Decimali: con punto (3.14) — inferito xsd:decimal
• Boolean: true / false — inferito xsd:boolean
• DateTime ISO 8601: "2026-05-26T14:30:00Z"^^xsd:dateTime
• Date: "2026-05-26"^^xsd:date

5. Relazioni tra istanze (Object properties)

Usare il namespace vuoto per riferimenti interni al file:

:DOC  a  stem:EntityStem ;
    stem:stemId         "DOC" ;
    stem:keyRole        "FK_CANDIDATE" ;
    stem:referencesKey  :CNT .   # ← riferimento ad altra istanza dello stesso file

Per riferimenti cross-file (es. istanza di questo file che punta a istanza di un altro), usare il namespace completo dell'altro file:

@prefix other: <urn:mde:abox:other-dataset#> .

:foo  a  some:Class ;
      some:relatedTo  other:bar .

Struttura del file .md companion

Frontmatter

---
title: ABox — <breve descrizione>
date: DD/MM/YYYY
---

Sezioni obbligatorie

1. # <Titolo> — h1

2. ## Cosa contiene — sintesi del dataset: quante istanze, di che classi, da quale documento sorgente sono state estratte

3. ## File — embed live del .ttl:

   ```text(./<dataset-name>.ttl)
   ```
   

4. ## Prerequisito — riferimento alle TBox che devono essere caricate prima:

   Le TBox layer0-stem e layer1-cobol devono essere già su urn:mde:tbox:.... Vedi ../TBox/load-all.md.

5. ## Carica su Fuseki — runnable PowerShell:

   ```powershell
   # @param DATASET — nome dataset Fuseki (default: <project-name>)
   # @param FUSEKI_URI — base URL del server Fuseki (default: http://localhost:3030)
   $dataset = "<DATASET>"
   $fuseki = "<FUSEKI_URI>"
   $file = "ontology\ABox\<dataset-name>.ttl"
   $graph = "urn:mde:abox:<dataset-name>"
   
   $body = Get-Content $file -Raw -Encoding UTF8
   $uri  = "$fuseki/$dataset/data?graph=$([uri]::EscapeDataString($graph))"
   
   Invoke-RestMethod -Uri $uri -Method PUT -ContentType "text/turtle; charset=utf-8" -Body $body
   Write-Output "OK: $file -> $graph"
   ```
   

6. ## Verifica (obbligatoria) — runnable SPARQL SELECT/ASK che dimostra utilità del grafo: una query mirata sul caso d'uso del dataset. Esempio per stem PK:

   ```powershell
   $dataset = "<DATASET>"
   $fuseki = "<FUSEKI_URI>"
   $query = @"
   PREFIX stem: <https://dedagroup.it/ontology/cobol2java/stem#>
   SELECT ?stem ?canonicalName ?usageCount
   FROM <urn:mde:abox:<dataset-name>>
   WHERE {
       ?stem a stem:EntityStem ;
             stem:keyRole ?role ;
             stem:canonicalName ?canonicalName ;
             stem:usageCount ?usageCount .
       FILTER(?role IN ("PK", "PK_CANDIDATE"))
   }
   ORDER BY DESC(?usageCount)
   "@
   $uri = "$fuseki/$dataset/query"
   $resp = Invoke-RestMethod -Uri $uri -Method POST -ContentType "application/sparql-query" -Body $query -Headers @{ Accept = "application/sparql-results+json" }
   foreach ($r in $resp.results.bindings) { ... }
   ```
   

Named graph convention

Il named graph IRI è sempre urn:mde:abox:<dataset-name>. Stesso pattern del TBox, ma con prefisso abox: invece di tbox:.

L'uso del named graph garantisce:

• Re-load idempotente via PUT
• Drop selettivo se si vuole rigenerare un singolo dataset senza toccare gli altri
• Filtraggio in SPARQL via FROM <urn:mde:abox:<dataset-name>> o GRAPH <urn:...> { ... }

Tracciabilità della sorgente — PROV-O opzionale

Per dataset estratti automaticamente da un documento, è raccomandato annotare la provenance:

@prefix prov: <http://www.w3.org/ns/prov#> .

:CNT  prov:wasDerivedFrom  <file:///docs/analisi/CWPGFG10.md> ;
      prov:wasGeneratedBy  :extraction-activity-001 .

:extraction-activity-001 a prov:Activity ;
    prov:startedAtTime "2026-05-26T14:30:00Z"^^xsd:dateTime ;
    prov:wasAssociatedWith :copilot-llm .

Non obbligatorio nella prima iterazione; aggiungere quando si vorrà tracciare quale documento ha generato quale istanza.

Validazione

Validare il .ttl prima del caricamento:

riot --validate ontology/ABox/<dataset-name>.ttl

Silenzio = OK.

Cosa NON fare

• ❌ Non includere definizioni di classi/proprietà (owl:Class, owl:DatatypeProperty) in un file ABox — quelle vivono solo in TBox
• ❌ Non inventare nuove proprietà non dichiarate nella TBox (RDF lo accetta ma il modello diventa inconsistente)
• ❌ Non usare i namespace pieni (lunghi) inline — definisci sempre prefissi all'inizio del file
• ❌ Non scrivere letterali numerici tra virgolette (es. stem:usageCount "47") — il range XSD non matcha
• ❌ Non saltare il namespace locale : — è quello che identifica le istanze come "appartenenti a questo file"

Esempio completo

Per un esempio concreto di ABox ben formata che applica queste convenzioni, vedi ontology/ABox/example-stems.{ttl,md} nel progetto Ontologies (3 istanze di EntityStem con tipi misti).

Vedi anche [[mde-tbox]] per la convenzione speculare di schema, e [[mde-features]] per la sintassi MDE-specific dei runnable e dei text(...) embed.