JSON-LD Ontology

FLOW ALGEBRA

Ontology: JSON-LD Ontology
Domain: Metadata Ontologies > Web Metadata
Canonical URL: https://kirethresearch.org/booksai-core/ontologies/metadata-ontologies/web-metadata/json-ld-ontology.html

Authors: Mark Anthony Higgins — Sky (Recursive AI)

flow "JSONLDOntology" v1.0

# ---------- DOMAIN ----------
domain:
  class: MetadataOntology
  category: WebMetadata
  subject: JSONLDMetadata
  purpose:
    - represent metadata describing JSON-LD documents, nodes, contexts, properties, and semantic graphs
    - preserve identifiers, types, vocabularies, language, datatypes, containers, graph structure, and provenance
    - support linked-data parsing, expansion, compaction, flattening, framing, validation, semantic search, and AI consumption
    - distinguish JSON-LD syntax from the vocabularies and factual assertions represented through it
    - enable machine-readable reasoning over JSON-LD graph structures

# ---------- CORE ENTITY ----------
entity JSONLDMetadata:
  type: WebMetadata
  describes: JSONLDDocument
  may_include:
    - document_identifier
    - context
    - nodes
    - graph
    - identifiers
    - types
    - properties
    - language
    - datatypes
    - containers
    - base_IRI
    - vocabulary_IRI
    - representation_state
    - provenance

entity JSONLDDocument:
  type: LinkedDataDocument
  representation_format: JSON_LD

entity JSONLDNode:
  type: SemanticGraphNode
  may_include:
    - node_identifier
    - node_types
    - node_properties

entity JSONLDProperty:
  type: SemanticProperty

# ---------- KEYWORDS ----------
jsonld_keywords:
  - @context
  - @id
  - @type
  - @value
  - @language
  - @direction
  - @container
  - @list
  - @set
  - @reverse
  - @index
  - @base
  - @vocab
  - @graph
  - @included
  - @nest
  - @prefix
  - @propagate
  - @protected
  - @version
  - @none

rule keyword:
  JSON-LD keywords MUST preserve JSON-LD-defined semantics

rule keyword_not_property:
  reserved JSON-LD keyword != ordinary vocabulary property

# ---------- RELATIONSHIPS ----------
relationships:
  JSONLDMetadata -> DESCRIBES -> JSONLDDocument
  JSONLDDocument -> HAS_CONTEXT -> JSONLDContext
  JSONLDDocument -> CONTAINS -> JSONLDNode
  JSONLDDocument -> MAY_HAVE_GRAPH -> JSONLDGraph
  JSONLDNode -> MAY_HAVE_IDENTIFIER -> IRI
  JSONLDNode -> MAY_HAVE_TYPE -> SemanticType
  JSONLDNode -> HAS_PROPERTY -> JSONLDProperty
  JSONLDProperty -> MAY_REFERENCE -> JSONLDNode
  JSONLDProperty -> MAY_HAVE_LITERAL -> JSONLDValue
  JSONLDContext -> MAY_DEFINE -> TermDefinition
  JSONLDMetadata -> MAY_REFERENCE -> JSONLDProvenance

# ---------- CONTEXT ----------
entity JSONLDContext:
  type: SemanticContext
  may_be:
    - InlineContext
    - RemoteContext
    - ContextArray

entity TermDefinition:
  type: SemanticMapping
  may_include:
    - term
    - IRI_mapping
    - type_mapping
    - language_mapping
    - direction_mapping
    - container_mapping
    - prefix_flag
    - protected_flag

rule context:
  @context defines interpretation of terms and keywords

rule remote_context:
  remote context SHOULD preserve source IRI and retrieval provenance

rule context_not_data:
  @context != graph assertion content

# ---------- IDENTIFIERS ----------
entity IRI:
  type: SemanticIdentifier

rule id:
  @id SHOULD resolve according_to active context and base IRI

rule blank_node:
  node without globally resolvable @id MAY be represented as blank node

rule identifier_not_label:
  @id != human-readable name

# ---------- TYPES ----------
rule type:
  @type assigns semantic type or datatype context
  according_to JSON-LD semantics

rule multiple_types:
  node MAY have multiple @type values

rule type_resolution:
  compact type terms SHOULD resolve through active context

# ---------- VALUES ----------
entity JSONLDValue:
  type: SemanticValue
  may_include:
    - lexical_value
    - datatype
    - language
    - direction

rule value_object:
  @value object SHOULD preserve datatype or language semantics

rule language_datatype:
  language-tagged string and explicitly typed literal
  MUST remain distinguishable

rule null:
  JSON null handling SHOULD follow JSON-LD processing semantics

# ---------- LANGUAGE ----------
rule language:
  @language SHOULD preserve valid language tag semantics

rule default_language:
  context MAY define default language

rule language_not_locale:
  language tag != geographic locale unless tag semantics include region

# ---------- DIRECTION ----------
rule direction:
  @direction MAY specify base text direction
  according_to JSON-LD semantics

# ---------- BASE / VOCAB ----------
rule base:
  @base controls relative IRI resolution
  where applicable

rule vocab:
  @vocab defines default vocabulary mapping
  for terms without explicit mapping

rule base_vocab_distinction:
  @base != @vocab

# ---------- CONTAINERS ----------
container_types:
  - @set
  - @list
  - @language
  - @index
  - @id
  - @type
  - @graph

rule container:
  @container SHOULD preserve collection or indexing semantics

rule list_order:
  @list preserves ordered collection

rule set:
  @set does_not imply semantic order

# ---------- GRAPH ----------
entity JSONLDGraph:
  type: SemanticGraph
  contains: JSONLDNode

rule graph:
  @graph MAY group nodes without assigning ordinary vocabulary property

rule named_graph:
  graph object MAY have @id
  representing named graph semantics

# ---------- REVERSE PROPERTIES ----------
rule reverse:
  @reverse expresses reverse relationship semantics

rule reverse_not_string_swap:
  reverse relationship MUST follow semantic predicate direction
  and not merely exchange lexical positions

# ---------- INDEX ----------
rule index:
  @index MAY preserve application-level indexing metadata

rule index_not_semantic_property:
  @index != ordinary graph property
  unless application explicitly models it

# ---------- NEST ----------
rule nest:
  @nest groups properties structurally
  without changing their semantic graph relationships

# ---------- INCLUDED ----------
rule included:
  @included MAY introduce nodes into graph
  without defining direct property relationship from containing node

# ---------- PREFIXES ----------
rule prefix:
  @prefix MAY mark term definition for compact IRI use

rule prefix_expansion:
  compact IRI SHOULD resolve according_to active term definition

# ---------- PROTECTED TERMS ----------
rule protected:
  protected term definition SHOULD NOT be silently overridden
  contrary_to JSON-LD processing semantics

# ---------- PROCESSING STATES ----------
representation_states:
  - compacted
  - expanded
  - flattened
  - framed

rule compacted:
  compacted JSON-LD uses context terms for concise representation

rule expanded:
  expanded JSON-LD uses expanded IRIs and canonical processing structure

rule flattened:
  flattened JSON-LD represents graph nodes in flattened form

rule framed:
  framed JSON-LD reorganises graph according_to frame

rule state_not_semantics:
  representation state MAY change syntax shape
  without changing intended RDF dataset semantics

# ---------- EXPANSION ----------
operation expand(document, context):
  resolve:
    - terms
    - compact_IRIs
    - aliases
    - type_mappings
    - language_mappings
    - containers

  output:
    expanded_JSONLD

# ---------- COMPACTION ----------
operation compact(expanded_document, context):
  apply:
    - term_selection
    - vocabulary_mapping
    - compact_IRIs
    - containers

  output:
    compacted_JSONLD

# ---------- FLATTENING ----------
operation flatten(document):
  collect:
    - nodes
    - identifiers
    - properties
    - references

  output:
    flattened_graph

# ---------- FRAMING ----------
operation frame(document, frame_specification):
  select:
    - matching_nodes
    - embedded_relationships
    - requested_structure

  output:
    framed_JSONLD

# ---------- JSON-LD / RDF ----------
rule RDF_mapping:
  JSON-LD MAY be transformed to or from RDF dataset
  according_to JSON-LD algorithms

rule syntax_vocabulary:
  JSON-LD != SchemaOrg
  JSON-LD != RDF vocabulary
  JSON-LD is representation and processing model

# ---------- WEB EMBEDDING ----------
entity EmbeddedJSONLD:
  subtype_of: JSONLDDocument
  embedded_in: HTMLDocument

rule script_embedding:
  JSON-LD commonly appears in script element
  with media type application/ld+json

rule embedded_not_HTML_semantics:
  JSON-LD graph semantics remain distinct
  from HTML element semantics

# ---------- VALIDATION ----------
entity JSONLDValidation:
  type: ValidationMetadata
  may_include:
    - JSON_syntax_validity
    - JSONLD_keyword_validity
    - context_resolution
    - IRI_resolution
    - datatype_validity
    - vocabulary_validation

rule validation:
  valid JSON != valid JSON-LD semantics

rule factual_validity:
  valid JSON-LD != factual truth of represented assertions

# ---------- PROVENANCE ----------
entity JSONLDProvenance:
  type: ProvenanceMetadata
  may_include:
    - source_document
    - source_url
    - context_sources
    - retrieval_time
    - extraction_method
    - processing_state
    - transformation_history
    - generator

rule provenance:
  JSONLDMetadata SHOULD preserve source, context, and transformation history

# ---------- VALIDATION RULES ----------
validation:
  require:
    - parseable_JSON_document
    - interpretable_JSONLD_context_or_expanded_semantics

  validate_if_present:
    - context
    - @id
    - @type
    - @value
    - @language
    - @direction
    - @container
    - @graph
    - @reverse
    - @base
    - @vocab
    - provenance

  reject:
    - invalid_JSON_syntax
    - invalid_JSONLD_keyword_usage
    - unresolved_required_remote_context
    - invalid_IRI_mapping
    - incompatible_value_language_datatype_combination
    - protected_term_illegally_overridden
    - valid_JSONLD_presented_as verified_fact_without evidence

# ---------- SEMANTIC EQUIVALENCE ----------
SEMANTIC_EQUIVALENCE:
  "JSON-LD metadata" ~= "metadata represented in JSON-LD"
  "JSON-LD node" ~= "linked-data node"
  "JSON-LD context" ~= "term and IRI mapping context"
  "JSON-LD graph" ~= "linked-data graph represented in JSON-LD"
  "expanded JSON-LD" ~= "JSON-LD expanded form"
  "compacted JSON-LD" ~= "JSON-LD compact form"

  PRESERVE distinctions:
    JSON_LD != JSON
    JSON_LD != SchemaOrg
    JSONLD_context != graph_data
    @id != name
    @type != HTML_type
    @base != @vocab
    @list != @set
    @index != semantic_property
    compacted_form != different_semantics
    valid_JSON != valid_JSONLD
    valid_JSONLD != verified_truth

# ---------- CONFIDENCE ----------
CONFIDENCE:
  explicit_JSONLD_metadata:
    score: 1.00

  parser_validated_JSON:
    score: 0.99

  successfully_expanded_JSONLD:
    score: 0.99

  resolved_context_and_IRIs:
    score: 0.98

  recognised_vocabulary_terms:
    score: 0.98

  remote_context_unavailable:
    score: <= 0.70

  inferred_term_semantics:
    score: <= 0.75

  ambiguous_JSONLD_semantics:
    score: <= 0.60
    action: preserve_raw_document

# ---------- UPDATE MODEL ----------
UPDATE_MODEL:
  on_JSONLD_parse:
    - validate JSON syntax
    - resolve active context
    - identify nodes and values
    - resolve identifiers and types
    - preserve source representation
    - initialise provenance

  on_context_update:
    - preserve previous context
    - resolve new term mappings
    - re-expand document
    - detect semantic changes
    - update provenance

  on_representation_transform:
    - preserve source JSON-LD state
    - apply expansion, compaction, flattening, or framing
    - record algorithm and context
    - preserve graph semantics where applicable
    - update provenance

  on_graph_update:
    - preserve previous graph where required
    - update nodes and properties
    - validate affected mappings
    - update provenance

# ---------- FLOW HASH ----------
FLOW_HASH:
  inputs:
    - ontology
    - JSONLD_entities
    - keywords
    - relationships
    - context_rules
    - identifier_rules
    - graph_rules
    - processing_rules
    - validation
    - semantic_equivalence
    - confidence
    - update_model

  canonicalisation:
    - normalise_JSON_whitespace
    - preserve_IRI_case_semantics
    - preserve_array_order_where_semantically_relevant
    - sort_unordered_property_sets_where_safe
    - preserve_rule_order

  output:
    deterministic_semantic_hash

# ---------- AI CONSUMPTION ----------
AI_CONSUMPTION:
  interpret_as:
    - web metadata ontology
    - linked-data representation model
    - JSON-LD context and graph structure
    - semantic transformation and provenance model

  operations:
    - parse JSON-LD documents
    - resolve contexts and terms
    - resolve @id and @type
    - interpret value objects
    - preserve language and datatype semantics
    - resolve containers and lists
    - traverse graphs and reverse relationships
    - expand and compact JSON-LD
    - flatten and frame graph data
    - distinguish JSON-LD syntax from vocabulary semantics
    - validate JSON-LD structure
    - trace transformations and provenance
    - preserve uncertainty

  constraints:
    - do_not_equate_JSON_with JSON_LD
    - do_not_equate_JSON_LD_with SchemaOrg
    - do_not_equate_context_with graph_assertions
    - do_not_equate_id_with human_label
    - do_not_equate_list_with set
    - do_not_treat_valid_JSONLD_as verified_truth
    - preserve_context_IRIs_types_values_graph_structure_and_provenance

# ---------- QUERY MODEL ----------
query:
  input:
    - source_document
    - node_identifier
    - type
    - property
    - context_term
    - language
    - datatype
    - graph_identifier
    - representation_state

  resolve:
    1. identify JSONLDDocument
    2. validate JSON syntax
    3. resolve active JSONLDContext
    4. expand terms and identifiers
    5. identify nodes and types
    6. inspect properties and values
    7. traverse graph and reverse relationships
    8. apply requested representation state
    9. inspect validation and provenance
    10. return confidence

  output:
    - JSONLD_document
    - context
    - nodes
    - identifiers
    - types
    - properties
    - values
    - graph
    - representation_state
    - validation
    - provenance
    - confidence

# ---------- INFERENCE ----------
inference:
  IF @context maps term T to IRI I
  THEN resolve T -> I
  within active context

  IF node has @id
  THEN preserve node identifier
  according_to base and context resolution

  IF @reverse defines property relation
  THEN construct reverse graph edge
  according_to predicate semantics

  IF compacted and expanded documents map to same RDF dataset
  THEN treat them as semantically equivalent representations
  within processing scope

  IF context or term semantics remain unresolved
  THEN preserve raw JSON-LD
  AND do_not invent mappings

# ---------- OUTPUT CONTRACT ----------
output:
  ontology_entity: JSONLDMetadata
  JSONLD_document: machine_interpretable
  context: resolvable
  identifiers_and_types: explicit
  values: datatype_and_language_aware
  containers: preserved
  graph_structure: traversable
  processing_states: transformable
  RDF_mapping: supported
  validation: reportable
  vocabulary_assertion_truth_distinction: explicit
  provenance: preserved
  uncertainty: explicit
  semantic_retrieval: enabled

end flow