DDD JSON¶

DDD JSON is Tala 31.0.1's preferred definition source format. It supports a bundle or separate component files. Component objects use explicit names and arrays rather than XML attribute bags.

Bundle and component roots¶

A bundle can be unwrapped or wrapped by a ddd key:

{
  "schema_version": "1.0",
  "ontology": {
    "name": "RoomBookingOntology",
    "sorts": [{"name": "room_type"}],
    "predicates": [{"name": "room_date", "sort": "datetime"}],
    "individuals": [],
    "actions": ["book_room"]
  },
  "domain": {
    "name": "RoomBookingDomain",
    "plans": [{
      "goal": {"perform": {"action": "book_room"}},
      "content": [
        {"findout": {"question": {"wh": {"predicate": "room_date"}}}},
        {"invoke_service_action": {"name": "BookRoom"}}
      ],
      "downdate_conditions": [{
        "in_beliefs_or_commitments": {
          "service_action_terminated": {"name": "BookRoom"}
        }
      }]
    }]
  },
  "service_interface": {
    "actions": [{
      "name": "BookRoom",
      "target": {"http": {"endpoint": "https://service.example/book-room"}},
      "parameters": [{"predicate": "room_date"}],
      "failure_reasons": ["unavailable"]
    }],
    "queries": [],
    "validators": []
  }
}

Each component may be stored separately with a root key: ontology, domain, or service_interface. Tala's ddd.config.json selects a bundle via ddd_bundle, or component files via ddd_files; ddd_bundle takes precedence when both settings are present.

Domain JSON concepts¶

The domain object contains ordered plans. A plan has a goal and ordered content array, and may have postplan where allowed. Goals use {"perform": {"action": "..."}} or {"resolve": {"question": ...}}. Questions use tagged objects such as wh, yn, kpq, or alt. A condition and each plan item use a single-key object, for example {"not": {...}} or {"findout": {...}}.

downdate_conditions is the JSON spelling for explicit plan downdating. The downdate_plan field remains in the JSON schema for compatibility but does not create implicit DME downdating in Tala/TDM 31.0.1.

Validation and loading¶

The Draft 2020-12 DDD JSON schemas are under tala/ddd/schemas/json/. Tests check the schemas against real fixtures and test bundle wrappers. DDDJSONCompiler converts DDD JSON to XML and passes it through the XML compiler; schema validity alone is not a substitute for compiler/loader tests.

The compiler also retains an XML-shaped structural JSON form using keys such as @, attrs, children, and items. Prefer the named component format for new DDDs; use structural JSON only when maintaining data that already depends on that compatibility form.

# From the Tala repository root, at the 31.0.1 source checkout:
source ~/python_3_11_environment/bin/activate
pytest tala/ddd/test/test_ddd_json_schemas.py
pytest tala/ddd/test/test_ddd_json_compiler.py

Keep DDD JSON distinct from JSON:API serialization of compiled DDD model objects. JSON:API has data/included resources and is used for runtime model interchange, not as DDD definition syntax.