Metadata-Version: 2.4
Name: information-model
Version: 2.1.0rc5
Summary: Information Model for describing Smart Content with rich metadata.
Author: IEC & ISO Single Delivery Unit
License-Expression: CC-BY-SA-4.0
Project-URL: Homepage, https://smartsdu.org/informationmodel
Project-URL: Documentation, https://smartsdu.bitbucket.io/docs/im/dev
Keywords: digitally enhanced content,standardization,ISO,IEC,ontology,rdf,shacl,knowledge graph
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE.md
Provides-Extra: docs
Requires-Dist: zensical; extra == "docs"
Provides-Extra: tests
Requires-Dist: pytest>=7; extra == "tests"
Requires-Dist: pytest-cov>=4; extra == "tests"
Requires-Dist: rdflib>=7.0.0; extra == "tests"
Requires-Dist: pyshacl>=0.27.0; extra == "tests"
Requires-Dist: owlready2>=0.46; extra == "tests"
Provides-Extra: all
Requires-Dist: information-model[docs,tests]; extra == "all"
Dynamic: license-file

# IEC-ISO Information Model for SMART content

The Information Model represents **fragments** of SMART **standards** and their content in
the W3C Resource Description Framework (RDF). It consists of a Core Ontology (OWL), SKOS
taxonomies, SHACL shapes and JSON-LD contexts.

## License

The information Model is released under the [CC BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/) open license.

## Scope

The Information Model describes the information and knowledge found in standards, whatever
their technical or non-technical domain. It covers:

- **Provisions and their structure**, as defined in the ISO/IEC Directives, Part 2: the eight
  provision types (Requirement, Recommendation, Permission, Instruction, Statement, Capability,
  Possibility, External Constraint), whether they are governing or assertional, their
  bindingness (normative or informative) and their supplements (notes, examples, footnotes).
- **Publication documents and their clauses**: title, abstract, issue date, edition,
  publication number and reference, project stage, publication type, and domain identifiers
  such as URNs (`schema:identifier`).
- **Representations and addressing**: each Provision, Clause and PublicationDocument has one
  or more representations (`dcat:Distribution`) with each specific media type, language, size, checksum and download URL. Provision and Clause are located in their source document with W3C Web Annotation selectors: RangeSelector, TextPositionSelector for Provision and XPathSelector for Clause.
- **Terms and definitions**: term entries (`skos:Concept`) and their preferred, admitted and
  deprecated terms (`skosxl:Label`), with term form, part of speech, country of use,
  pronunciation, notes to entry, examples and provenance.
- **Controlled vocabularies**: eight SKOS taxonomies (bindingness, provision, provision
  supplement, publication, publication component, term form, part-of-speech and identifier
  types).
- **Validation and exchange**: SHACL shapes (in JSON-LD) to check conformance, and JSON-LD
  contexts to exchange data, for example through the SMART Content API.


## Installation

The Information Model is published on PyPI as the Python package `information-model`. The
package contains the ontologies, taxonomies, SHACL schemas and JSON-LD contexts, and
requires Python 3.11 or later. We recommend installing it in a Python virtual environment.

### Install with pip

#### macOS / Linux

``` bash
python3 -m venv .venv
source .venv/bin/activate
pip install information-model
```

#### Windows (PowerShell)

``` powershell
python -m venv .venv
.venv\Scripts\Activate.ps1
pip install information-model
```

To install a given version, e.g. `2.1.0`, use `pip install "information-model==2.1.0"`.

### Install with uv

``` bash
uv init
uv add information-model
```

### Use the packaged files

The package gives access to its files by their path in the package. The example below also
loads a file with [rdflib](https://rdflib.readthedocs.io/), which is not installed with the
package. Install it in the same virtual environment:

``` bash
pip install rdflib
```

Then:

``` python
import information_model

print(information_model.__version__)

# Read a file as text
turtle = information_model.read_text("ontologies/core-ontology.ttl")

# Or get a file path, e.g. to load it with rdflib
from rdflib import Graph

with information_model.as_path("schemas/shacl/schemas.shacl.ttl") as path:
    shapes = Graph().parse(path)
```

The main paths are `ontologies/core-ontology.ttl`, `ontologies/external/vocabulary.ttl`,
`taxonomies/*.ttl`, `schemas/shacl/jsonld/`, `schemas/shacl/ttl/`,
`schemas/shacl/schemas.shacl.ttl` and `jsonldcontext/`.

### Without Python

The files of each version are also available without installing anything:

- in the [Information Model browser](https://smartsdu.bitbucket.io/docs/im/browse/), under
  `raw/` in each version, e.g. `https://smartsdu.bitbucket.io/docs/im/browse/2.1.0/raw/`;
- as Python package files on [PyPI](https://pypi.org/project/information-model/#files).

## Development Setup Instructions

Requires Python 3.11 or later.

### 1. Create a Virtual Environment

From the repository root:

``` bash
python -m venv .venv
```

Activate it:

#### macOS / Linux

``` bash
source .venv/bin/activate
```

#### Windows (PowerShell)

``` powershell
.venv\Scripts\Activate.ps1
```

------------------------------------------------------------------------

### 2. Upgrade pip (recommended)

``` bash
python -m pip install --upgrade pip
```

------------------------------------------------------------------------

### 3. Install Packages in Editable Mode

From the repository root:

``` bash
pip install -e .
```

Editable mode (`-e`) ensures:

-   The packages are importable
-   Changes in the source code are immediately reflected
-   No wheel build is required during development

#### Install Optional Dependency Sets (Extras)

The base install:

``` bash
pip install -e .
```

only installs core package dependencies. This project also defines optional
dependency groups in `pyproject.toml`:

- `tests`: testing tools (`pytest`, `pytest-cov`, `rdflib`, `pyshacl`)
- `docs`: documentation tooling (`zensical`)
- `all`: includes both `docs` and `tests`

Install a specific extra:

``` bash
pip install -e ".[tests]"
```

Install everything:

``` bash
pip install -e ".[all]"
```

If you want to run tests with `pytest`, install at least `.[tests]`.


##### When do I need to re-run this?

You only need to re-run the `pip install -e ...` commands if:
- You modify a pyproject.toml file (e.g. add/change dependencies, version, package metadata)
- You change package configuration such as package-data
- You recreate or delete your virtual environment

**You do not need to re-run them when editing:**
- Python source files (.py)
- Test files
- Ontology files (.ttl, .owl, etc.)

Editable mode automatically reflects those changes.

------------------------------------------------------------------------

### 4. Run Tests

``` bash
pytest
```

The schema tests in `tests/schemas_test/` use pySHACL to meta-validate the
JSON-LD SHACL schemas under `information_model/schemas/shacl`. These tests
require the schemas' JSON-LD `@context` values to be loadable and to expand the
schema documents into SHACL triples.

To get a coverage report:
``` bash
pytest --cov
```

<details>
<summary>Java requirement for ontology consistency tests</summary>

The Owlready2-based ontology consistency test in `tests/ontology_consistency_test/` requires Java to be installed locally. The test will fail if Java is not available.

**macOS (Homebrew):**
``` bash
brew install openjdk
sudo ln -sfn "$(brew --prefix openjdk)/libexec/openjdk.jdk" /Library/Java/JavaVirtualMachines/openjdk.jdk
export PATH="$(brew --prefix openjdk)/bin:$PATH"
java -version
```

**Linux (Debian/Ubuntu):**
``` bash
sudo apt-get update
sudo apt-get install -y default-jre
java -version
```

**Windows:**

Install a JRE or JDK such as Eclipse Temurin or Microsoft Build of OpenJDK, then open a new terminal and verify:

``` powershell
java -version
```

</details>

------------------------------------------------------------------------
### 5. Update and generate the documentation

The documentation uses [zensical](https://github.com/zensical/zensical) as template. Install the required packages:

``` bash
pip install ".[docs]"
```

Edit file in `./docs` folder to update the documentation. 
Run the following command to preview the documentation as changes are made:

``` bash
zensical serve
```
Go to localhost:8000 to view the documentation.

Generate the full documentation:

``` bash
zensical build
```

#### Generate the versioned documentation locally

The published documentation (<https://smartsdu.bitbucket.io/docs/im/dev/>) has one copy
per released version and a version selector in the header. Zensical has no native
versioning, so each version is built with the Zensical compatible fork of
[mike](https://github.com/squidfunk/mike), which stores every build in a subdirectory
(`docs/im/dev/<version>`) of a Git branch. The mike settings are in `zensical.toml`
(`[project.plugins.mike]` and `[project.extra.version]`), and the commands below use the
same flags as the Bitbucket pipeline, which publishes the documentation on every `X.Y.Z`
tag.

Install mike, which is not on PyPI:

``` bash
pip install "mike @ git+https://github.com/squidfunk/mike.git"
```

Build the current checkout as a version, e.g. `2.1.0`, and make the alias `latest` point to
it. mike commits the build to the local branch `site-deploy` (created if needed); your
working tree and current branch are not changed, and nothing is pushed:

``` bash
mike deploy --branch site-deploy --deploy-prefix docs/im/dev \
  --alias-type=copy --update-aliases --title 2.1.0 2.1.0 latest
mike set-default --branch site-deploy --deploy-prefix docs/im/dev latest
```

To add more versions, check out each one and deploy it without `latest`, e.g.:

``` bash
git checkout 2.0.0
mike deploy --branch site-deploy --deploy-prefix docs/im/dev --title 2.0.0 2.0.0
git checkout -
```

The Markdown links to the ontology reference (`docs/im/browse/`), which redirects to its
latest version. The pipeline points each version at its own copy of the reference
(`docs/im/browse/<version>/`) by running, just before `mike deploy`:

``` bash
python tests/docs_utils/pin_browse_links.py 2.1.0
```

The script edits the Markdown files in place. To do the same locally, run it before
`mike deploy` and restore the files afterwards with `git checkout -- docs`. Without it, the
links of a local build go to the latest version of the reference.

List the versions and serve the site:

``` bash
mike list --branch site-deploy --deploy-prefix docs/im/dev
mike serve --branch site-deploy
```

Go to <http://localhost:8000/docs/im/dev/>, which redirects to `latest`. The version
selector lists the versions in `site-deploy`, and every version other than `latest` shows
the outdated-version banner.

To preview a new version next to the ones already published, start `site-deploy` from the
published site before deploying (this only fetches it):

``` bash
git fetch git@bitbucket.org:smartsdu/smartsdu.bitbucket.io.git "+main:site-deploy"
```

Delete the branch when done:

``` bash
git branch -D site-deploy
```


### 6. Run a Script Manually

After installing in editable mode, you can run scripts that import the
package:

``` python
from information_model.assets import as_path

with as_path("ontologies/core-ontology.ttl") as p:
    print(p.read_text())
```

Without installing the packages first, imports like `information_model`
will fail.

## References

This work is essentially derived and repackaged from the Standard Information Model created by the IEC SG12 SIM group.
