# gist

GIST (Semantic Arts, Upper Enterprise Ontology) - LinkML Schema

This repository is an independent LinkML rendering of [gist](https://github.com/semanticarts/gist), Semantic Arts' upper enterprise ontology. It is not a Semantic Arts release, and it defines nothing in gist's namespace.

> **Only want to ask?** Install `ktl-docent` into any agent you use, by a route from [the install page](https://w3id.org/ktl/docs/install/), and ask it about this repository. It answers from the bundle and says how far each answer has been checked.
>
> **Agents:** if `.lokf/knowledge/index.md` exists, read it first. `llms.txt` says how to weigh it.

## Documentation Website

[https://lmodel.github.io/gist](https://lmodel.github.io/gist)

## Repository Structure

* [docs/](https://github.com/lmodel/gist/tree/bf0bec974ebb255df029512ce82d7502cdbe69ca/docs): the documentation pages the website shows
  * [elements/](https://lmodel.github.io/gist/schema/): generated schema documentation
* [examples/](https://github.com/lmodel/gist/tree/bf0bec974ebb255df029512ce82d7502cdbe69ca/examples): examples of using the schema
* [project/](https://github.com/lmodel/gist/tree/bf0bec974ebb255df029512ce82d7502cdbe69ca/project): generated project files (do not edit them)
* [src/](https://github.com/lmodel/gist/tree/bf0bec974ebb255df029512ce82d7502cdbe69ca/src): source files (edit these)
  * [gist](https://github.com/lmodel/gist/tree/bf0bec974ebb255df029512ce82d7502cdbe69ca/src/gist)
    * [schema/](https://github.com/lmodel/gist/tree/bf0bec974ebb255df029512ce82d7502cdbe69ca/src/gist/schema): the LinkML schema (edit this)
    * [datamodel/](https://github.com/lmodel/gist/tree/bf0bec974ebb255df029512ce82d7502cdbe69ca/src/gist/datamodel): the generated Python datamodel
* [tests/](https://github.com/lmodel/gist/tree/bf0bec974ebb255df029512ce82d7502cdbe69ca/tests): Python tests
  * [data/](https://github.com/lmodel/gist/tree/bf0bec974ebb255df029512ce82d7502cdbe69ca/tests/data): example data
* [website/](https://github.com/lmodel/gist/tree/bf0bec974ebb255df029512ce82d7502cdbe69ca/website): the documentation website, an Astro Starlight site built from the README, `docs/`, the schema's pages and the knowledge bundle

## Developer Tools

The project's predefined recipes run with the command runner [just](https://github.com/casey/just/).
To list them, run `just` or `just --list`.

## Knowledge Trust Ladder (KTL)

`.lokf/` holds this project's [KTL](https://w3id.org/ktl/) knowledge bundle, which validates against LOKF's own schema.

Each release also attaches `gist-linkml-lokf-<tag>.yaml`, for a bundle whose domain schema imports gist. It is `gist_core.yaml` as `lokf adapt` rewrites it, and `just gen-lokf-copy` builds the same file. Save it beside `lokf.yaml` as `gist_core_lokf.yaml` and import `gist_core_lokf`. In the copy, these classes are re-rooted on LOKF's `Concept`, so a concept may name any gist class but `GistThing` and `Any` as its `type`:

```text
Aspect, Category, Component, Composite, Content, Event, GeoLocation, IntellectualProperty, Intention, Language, Magnitude, GistOrganization, PhysicalIdentifiableItem, PhysicalSubstance, SchemaMetaData, Template, TemporalRelation, TimeInterval, UnitOfMeasure
```

`Person`, `Organization`, `name`, `description` and `license` are `GistPerson`, `GistOrganization`, `gist_name`, `gist_description` and `gist_license` in the copy, because `lokf.yaml` defines those names; each keeps its gist IRI. A slot ranged over a gist class takes the IRI of the concept it names.

## License and attribution

gist is Semantic Arts' upper ontology, published under
[CC BY 4.0](https://creativecommons.org/licenses/by/4.0/). This schema is
derived from the gist 14.1.0 release.
[scripts/gist_to_linkml.py](https://github.com/lmodel/gist/blob/bf0bec974ebb255df029512ce82d7502cdbe69ca/scripts/gist_to_linkml.py) converts its OWL modules
to LinkML. Their RDFS annotations and subclass assertions are merged into the
schema, and SSSOM mappings to other vocabularies are added from
[src/gist/mappings/](https://github.com/lmodel/gist/tree/bf0bec974ebb255df029512ce82d7502cdbe69ca/src/gist/mappings). The release is kept unmodified in
[upstream/](https://github.com/lmodel/gist/tree/bf0bec974ebb255df029512ce82d7502cdbe69ca/upstream/gist14.1.0_webDownload) with its
[LICENSE.txt](https://github.com/lmodel/gist/blob/bf0bec974ebb255df029512ce82d7502cdbe69ca/upstream/gist14.1.0_webDownload/LICENSE.txt). The code in this
repository is Apache-2.0 ([LICENSE](https://github.com/lmodel/gist/blob/bf0bec974ebb255df029512ce82d7502cdbe69ca/LICENSE)). [NOTICE](https://github.com/lmodel/gist/blob/bf0bec974ebb255df029512ce82d7502cdbe69ca/NOTICE) lists every
third-party work it carries or derives from, and is included in the package.

Semantic Arts also asks that terms used from gist stay in the gist namespace
and that nobody else defines terms there. The schema and every generated
artefact hold to both:

* **`gist:`** (`https://w3id.org/semanticarts/ns/ontology/gist/`) and
  **`gistd:`** are Semantic Arts' namespaces. Every gist class, property and
  individual keeps its gist IRI.
* **`gist_linkml:`** (`https://w3id.org/lmodel/gist/`) is this project's
  namespace. It holds only what the LinkML rendering adds: the schema
  documents, the `GistThing` mixin, the types for the datatypes
  `linkml:types` lacks, the enums, the subsets, the SHACL shapes, and the
  LinkML element definitions the OWL links to the gist terms they render.
* Tests in [tests/test_schema_validation.py](https://github.com/lmodel/gist/blob/bf0bec974ebb255df029512ce82d7502cdbe69ca/tests/test_schema_validation.py)
  and [tests/test_generated_artifacts.py](https://github.com/lmodel/gist/blob/bf0bec974ebb255df029512ce82d7502cdbe69ca/tests/test_generated_artifacts.py)
  check both rules against the vendored release.

## Contributing and security

[CONTRIBUTING.md](https://github.com/lmodel/gist/blob/bf0bec974ebb255df029512ce82d7502cdbe69ca/CONTRIBUTING.md) is the checklist for a pull request and
for releasing. [AI_COVENANT.md](https://github.com/lmodel/gist/blob/bf0bec974ebb255df029512ce82d7502cdbe69ca/AI_COVENANT.md) sets the rules for AI-assisted
work. [SECURITY.md](https://github.com/lmodel/gist/blob/bf0bec974ebb255df029512ce82d7502cdbe69ca/SECURITY.md) says how to report a vulnerability.
[CHANGELOG.md](https://github.com/lmodel/gist/blob/bf0bec974ebb255df029512ce82d7502cdbe69ca/CHANGELOG.md) records the changes.

## Credits

This project uses the template [linkml-project-copier](https://github.com/linkml/linkml-project-copier).