arrow_back_ios_new

Synced automatically from infinity-project/rulebook (main) at build time – edit the source repository, not this file.

Semantic layer development and documentation

← Back to index

Ontology development guidelines

  • The namespace of the ontology (published within the INFINITY Organization through a repository with component type “Ontology”) must follow this rule:
    • Rule: https://w3id.org/infinity/ontology/[name-of-the-ontology]
    • This rule is in line with the recommendations for URIs found in the literature, specifically those by the ISA project, since it uses a dedicated service (w3id.org) and mentions the resource type (ontology) along with the specific ontology name.
    • A preferred prefix should be indicated for each namespace, e.g. mkg: https://w3id.org/infinity/ontology/mkg
  • The ontology should be annotated with labels (rdfs:label) and comments (rdfs:comment).
  • The ontology should contain alignments to possible reuse of Open Data Patterns:
    • Such alignments make it explicit which patterns have been reused, supporting pattern-based exploration and guaranteeing interoperability between ontologies at the level of patterns.
    • Alignments should be expressed through the OPLaX ontology, which reuses and extends state-of-the-art patterns for annotation languages.
    • See an example of an ontology annotated with reused patterns.
  • The ontology should contain alignments to possible ontologies produced by INFINITY partners and reused within the project.
  • The ontology should avoid unnecessary complexity, or ensure it can be used both with and without different levels of semantic expressiveness.
    • An ontology should have a base version (definition of classes and properties/relations) which can be extended by layers of more expressivity (subclasses, subproperties, relation constraints, etc.).

Ontology documentation guidelines

  • Each ontology (published within the INFINITY Ontology network) should be stored as an RDF/OWL file in a separate repository.
  • The repository name should follow this rule:
    • Rule: [name-of-ontology]-ontology (e.g. mkg-ontology)
  • The repository’s metadata should identify this component as type “Ontology”.
  • Documentation of the ontology in README.md:
    • Must contain a brief description of the scope of the ontology.
    • Should contain useful statistics about the ontology (number of classes, number of properties, etc.) following OMV 2.0 and Dublin Core.
    • Must contain examples of relevant Competency Questions with respective SPARQL queries.
    • Must contain a graphical representation of classes and predicates.
    • Should contain the license for permitted use of the ontology.
  • The repository must include a separate folder containing ontology tests following eXtreme Design methodology (recommended tool: XDTesting).
  • For ontologies produced by INFINITY partners and reused within the project but published outside the INFINITY Organization, there should exist a reference to the ontology in an external-ontologies repository.

Knowledge graph development and documentation guidelines

Knowledge graph development guidelines

  • The namespace of the knowledge graph (published within INFINITY) needs to follow the rule:
    • Rule: https://w3id.org/infinity/resource/[class-local-name]/[SHA-1 hash of the unique attribute(s) of the individual]
    • Example: https://w3id.org/infinity/resource/PoliticalView/ec68f1e4727ecdd5272d247f3e3176743e38b469 for an entity of type PoliticalView, with the hash generated from the concatenation of the title and description of that particular instance.
    • This rule follows the ISA project’s URI recommendation: http://{domain}/{type}/{concept}/{reference}, where domain = host + relevant sector (w3id.org/infinity/), type = resource type (resource/), concept = the real-world object type ([class-local-name]), reference = a specific item (SHA-1 hash). See the ISA study on persistent URIs for more information.
  • The knowledge graph should contain alignments of its own resources to equivalents in other public KGs, e.g. owl:sameAs to Wikidata URIs.
  • The knowledge graph should be published as JSON-LD at least (other representations may also be made available as required by users).
  • The knowledge graph needs to be deployed on the web through an API endpoint containing all relevant prefixes and supporting, as far as possible, standardized query and retrieval formats for humans and AI agents (e.g. SPARQL, REST, GraphQL, vector-based search).

Knowledge graph documentation guidelines

  • The knowledge graph must be documented in a repository following the general rules already defined in this rulebook.
  • The name of the KG repository should follow this rule:
    • Rule: [name-of-kg]-kg (e.g. politics-kg)
  • The repository’s metadata should identify this component as type “Knowledge Graph”.
  • Documentation of the KG in README.md:
    • Must contain a brief description of the scope of the knowledge graph.
    • Must contain the link to the (API) endpoint.
    • Should contain useful statistics about the knowledge graph (number of classes, number of properties, etc.) following DCAT-AP and VoID.
    • Should contain paradata, i.e. define how the content of the KG was created.
    • Should contain examples of relevant Competency Questions with respective SPARQL queries.
    • Should contain the license for permitted data reuse.
  • A copy of the KG data (as Linked Open Data) should be hosted or linked to in a dedicated folder in the repository (data dump). If the data volume exceeds 500MB, split the data into different files. If data are difficult to split, use ntriples / quads serialisation. Otherwise, any other standard serialisation is acceptable.

← Previous: Software and data management · Back to index · Next: Becoming part of the INFINITY ecosystem →