# Open world and scope

> Folio keeps RDF's single global scope and uses datasets and profiles to decide what to put in front of you.

Source: https://semvia.io/docs/modeling/open-world-and-scope

Folio keeps [RDF](https://www.w3.org/TR/rdf11-concepts/)'s single global scope and uses datasets and profiles to decide what to put in front of you.

## One global scope

In RDF, every name is a URI (Uniform Resource Identifier), usually a web address, shared with the whole world. Nothing stops two people from defining the same idea. Here are two definitions of Person:

- **Person** — Defined by example.org: `http://example.org/Person`
- **Person** — Defined by [schema.org](https://schema.org/), the vocabulary Google and other search engines read: `https://schema.org/Person`

These look the same, but their authors are free to define them however they like. Their full names differ, so to RDF they are two different things, and both stay. Nothing links them unless someone says they mean the same.

That suits a world of billions of separate sources that never agreed on names in advance. It also makes RDF hard to work in: when every name from every source is available everywhere, how does a tool show you the ones that matter to what you are writing?

## How other languages work

Programming languages hit the same problem long ago. Thousands of libraries are public, and you still only want to see the names your own code uses. [Rust](https://doc.rust-lang.org/book/ch07-01-packages-and-crates.html), [Go](https://go.dev/ref/mod), [Java](https://docs.oracle.com/javase/specs/jls/se21/html/jls-7.html) and [TypeScript](https://nodejs.org/api/packages.html#subpath-exports) each settle on roughly four levels:

| The unit you… | Rust / Cargo | Go | Java / Maven | TypeScript / pnpm |
| --- | --- | --- | --- | --- |
| **Commit** | Workspace | Workspace (`go.work`) | Multi-module build | Workspace |
| **Install** | Package | Module (`require`) | Artifact (`dependency`) | Package (`dependencies`) |
| **Import** | Crate (`use`) | Package (`import`) | Package (`import`) | Subpath export (`foo/bar`) |
| **Edit** | Source file | Source file | Compilation unit (`.java`) | Module file |

- **Commit**: what you check in to source control and work on as one. It can hold many of the units you install, each with a version of its own.
- **Install**: what others release and you depend on, listed in a manifest such as `Cargo.toml`, `go.mod`, `pom.xml` or `package.json`. Each release has its own version, and installing makes its code available, not visible.
- **Import**: what your code names to bring its names into view. This is where scope is decided.
- **Edit**: the file you write in, where the editor checks the names you use.

The words don't line up. "Package" is the install level in Rust and TypeScript and the import level in Go and Java, and "module" means something different in every column. The levels do line up: in all four, you install one unit and import another.

Folio uses the same four levels. Here is the table again with Folio added:

| The unit you… | Folio | Rust / Cargo | Go | Java / Maven | TypeScript / pnpm |
| --- | --- | --- | --- | --- | --- |
| **Commit** | Workspace | Workspace | Workspace (`go.work`) | Multi-module build | Workspace |
| **Install** | Semantic package (`requires`) | Package | Module (`require`) | Artifact (`dependency`) | Package (`dependencies`) |
| **Import** | Dataset (`conformsTo`) | Crate (`use`) | Package (`import`) | Package (`import`) | Subpath export (`foo/bar`) |
| **Edit** | File | Source file | Source file | Compilation unit (`.java`) | Module file |

- **A workspace** is what's in source control, as in Cargo and pnpm. It can hold several semantic packages, each released with a version of its own.
- **A semantic package** is what you release and install, with `requires` in the manifest, `sem.json`. Every dataset in it can be named, as in Go with no `internal/` directory.
- **A dataset** is what you import, with `dct:conformsTo`. A dataset can narrow what it offers with [PROF](https://www.w3.org/TR/dx-prof/) profile semantics, as `exports` does in TypeScript and Java modules.
- **A file** is what you edit.

## What Folio scopes

Folio uses these levels to decide what is in scope for the file you have open at any given moment. That scope decides three things:

- **Which terms it is expected to use.** A term from outside its scope is marked with a warning.
- **Which terms typeahead offers first.** Terms in scope rank ahead of the rest.
- **Which [SHACL](https://www.w3.org/TR/shacl/) shapes check it.** Shapes run against the dataset's scope as a closed world: whatever a shape requires and the scope doesn't state is reported as missing.

***

## Workspaces and semantic packages

The manifest, `sem.json`, describes a semantic package. The one at the root of a workspace describes the workspace's own semantic package, which holds every file no dataset claims. Its `conformsTo` sets the vocabularies and schemas a file uses by default, when neither the file nor its dataset names any. `requires` lists the semantic packages it installs:

```
{
  "@context":
    "https://pkg.semvia.io/semvia/core/json-schema/context/semantic-package.json",
  "@type": "https://pkg.semvia.io/semvia/core/semantic-package#SemanticPackage",
  "title": { "en": "plants-scope" },
  "version": "0.0.0",
  "baseIRI": "https://example.org/my-semantic-package",
  "workspace": { "members": [] },
  "requires": [
    {
      "@type": "https://pkg.semvia.io/semvia/core/semantic-package#PackageRequirement",
      "package": "https://example.org/units/",
      "versionMinimum": "1.0.0"
    }
  ]
}
```

Installing is not scoping. `requires` installs a semantic package and everything it requires, and puts nothing in scope. A file uses what an installed semantic package offers only when something in it is named by the file's `dct:conformsTo`, its dataset's, or the `conformsTo` of the root `sem.json`.

## Datasets are the scope unit

A dataset is an `svds:Dataset` that claims a folder with `svds:memberSpace`. The files in that folder see each other's declarations, and each file belongs to the nearest dataset that claims it.

For example, say a power company defines its operations in a workspace with two datasets. Plants defines what a power plant is. Fleet describes the plants the company operates, one file per plant. Each folder declares its dataset with an `svds:Dataset` resource. The file can have any name; here it's `dataset.ttl` for clarity:

```
plants-scope/
├── sem.json
├── plants/               ← dataset “Plants”
│   ├── dataset.ttl       declares Plants
│   └── plants.ttl        defines :PowerPlant
└── fleet/                ← dataset “Fleet”
    ├── dataset.ttl       declares Fleet
    └── desert-ridge.ttl  one plant
```

`fleet/dataset.ttl` claims the fleet folder, and conforms to [Dataset and Package](https://semvia.io/docs/modeling/built-in-profiles#dataset-and-package). In a dataset file, `<>` names both the file and the dataset, so that line is also Fleet's `dct:conformsTo`, and Fleet's files conform to Dataset and Package too:

```turtle
@prefix dct: <http://purl.org/dc/terms/> .
@prefix svds: <https://pkg.semvia.io/semvia/core/dataset#> .

<> dct:conformsTo <https://pkg.semvia.io/semvia/core/profiles/dataset-and-package> .

# Fleet: every file in the fleet folder.
<> a svds:Dataset ;
  dct:title "Fleet"@en ;
  svds:memberSpace <./> .
```

`fleet/desert-ridge.ttl` describes one plant with `plants:PowerPlant`, `plants:name` and `plants:capacityMW`, which `plants/plants.ttl` defines:

```turtle
@prefix plants: <https://example.org/my-semantic-package/plants#> .
@prefix : <https://example.org/my-semantic-package/fleet#> .

# Desert Ridge Solar, one plant the company operates.
:desert-ridge a plants:PowerPlant ;
  plants:name "Desert Ridge Solar" ;
  plants:capacityMW 240.0 .
```

`plants/plants.ttl` sits in another dataset, so Fleet doesn't see its declarations. Folio marks the three terms the file takes from Plants, `plants:PowerPlant`, `plants:name` and `plants:capacityMW`, with a warning, and the tooltip on `plants:PowerPlant` reads "Nothing in this document's datasets or profiles declares the class".

Figure: fleet/desert-ridge.ttl open in Folio. The Profile button reads Dataset and Package · inherited. plants:PowerPlant, plants:name and plants:capacityMW carry warning marks, and the tooltip on plants:PowerPlant reads: Nothing in this document's datasets or profiles declares the class <https://example.org/my-semantic-package/plants#PowerPlant>.

Fleet doesn't use Plants yet, so the terms the file takes from Plants are marked.

The point of the boundary is to help whoever is writing, person or agent. Plants doesn't need Fleet: someone editing `plants/plants.ttl` is defining what a power plant is, and every plant the company operates would just be noise in typeahead and wasted context. Because Plants doesn't use Fleet, Folio offers only what's relevant to Plants. The warnings in Fleet are the same rule seen from the other side: Fleet hasn't said yet that it uses Plants.

The warnings change nothing in the graph. `plants.rq`, a query created from the new-file menu's **SPARQL Query** entry, still finds the plant:

```sparql
PREFIX plants: <https://example.org/my-semantic-package/plants#>

SELECT ?name ?capacity
WHERE {
  # Each plant's name and its capacity in megawatts.
  ?plant plants:name ?name ;
    plants:capacityMW ?capacity .
}
# Largest first.
ORDER BY DESC(?capacity)
```

Figure: The Results tab with 1 row, in two columns, name and capacity: Desert Ridge Solar, 240.

The one row is Desert Ridge Solar and its capacity, answered while its file still warns.

Datasets can nest. Say the company gives its solar plants a dataset of their own, Solar, in `fleet/solar/`. Each file there belongs only to Solar, the nearest dataset that claims it. So Fleet doesn't see the solar files' declarations, even though they sit inside its folder. Go works the same way: a package doesn't see the packages in its subdirectories.

```
fleet/                     ← dataset “Fleet”
├── dataset.ttl
├── desert-ridge.ttl
└── solar/                 ← dataset “Solar”
    ├── dataset.ttl        claims fleet/solar/
    └── sunrise-mesa.ttl
```

To let Fleet see them, say so in one of the two `dataset.ttl` files: `dct:hasPart` in Fleet's, naming Solar, or `dct:isPartOf` in Solar's, naming Fleet, both [Dublin Core terms](https://www.dublincore.org/specifications/dublin-core/dcmi-terms/). The [dataset-membership rule](https://semvia.io/docs/modeling/inference#dataset-membership) states it in full.

## Profiles define what you use

Every `svds:Dataset` is also a [PROF profile](https://www.w3.org/TR/dx-prof/#Class:Profile), so others can use its vocabulary and shapes. A file or a dataset names the vocabularies and schemas it uses with `dct:conformsTo`. Each one adds its terms and shapes to the scope of the datasets that hold the file, and never takes that scope away. Because every dataset is a profile, a file can conform to a dataset directly, including one in an installed semantic package.

Back to the example: one line in `fleet/dataset.ttl` clears the warnings. Fleet now conforms to Plants, so every file in the fleet folder can use what Plants defines:

```turtle
@prefix dct: <http://purl.org/dc/terms/> .
@prefix svds: <https://pkg.semvia.io/semvia/core/dataset#> .

<> dct:conformsTo <https://pkg.semvia.io/semvia/core/profiles/dataset-and-package> .

# Fleet: every file in the fleet folder, using Plants.
<> a svds:Dataset ;
  dct:title "Fleet"@en ;
  dct:conformsTo <../plants/dataset> ;
  svds:memberSpace <./> .
```

`<../plants/dataset>` is Plants' address, written relative to this file. [A file's address](https://semvia.io/docs/modeling/built-in-profiles#semvia-authoring-profile) is the workspace's base address followed by the file's path, without the extension.

Figure: fleet/desert-ridge.ttl open in Folio after the fix, with no term carrying a mark. The Profile button reads Plants, Dataset and Package.

Fleet conforms to Plants, so every term the file uses is in scope.

By default, a dataset offers all the vocabulary and shapes defined in it. Its author can override that and offer only specific ones with `prof:hasResource`, as [How profiles work](https://semvia.io/docs/modeling/how-profiles-work#what-a-profile-is) shows.

PROF gives a profile two ways to pull in another:

- `prof:isProfileOf` **builds on** another profile. If you use it, you get the whole chain.
- `dct:conformsTo` **uses** another profile. It doesn't chain: a dataset's `dct:conformsTo` applies to that dataset and doesn't pass to anyone who uses it.

Contrast this with [OWL](https://www.w3.org/TR/owl2-overview/)'s `owl:imports`, which doesn't differentiate consuming from extending: everything imported always passes on to whoever imports you.

In the example, Plants builds on Semvia's Class Schema, the vocabulary for writing classes:

```turtle
@prefix dct: <http://purl.org/dc/terms/> .
@prefix prof: <http://www.w3.org/ns/dx/prof/> .
@prefix svds: <https://pkg.semvia.io/semvia/core/dataset#> .

<> dct:conformsTo <https://pkg.semvia.io/semvia/core/profiles/dataset-and-package> .

# Plants: what a power plant is, built on Class Schema.
<> a svds:Dataset ;
  dct:title "Plants"@en ;
  prof:isProfileOf <https://pkg.semvia.io/semvia/core/profiles/class-schema> ;
  svds:memberSpace <./> .
```

Fleet conforms to Plants, so Fleet's files get Plants and, through the chain, Class Schema. What Plants itself conforms to, Dataset and Package, stays with Plants and isn't handed on. Fleet's files have Dataset and Package from Fleet's own `dct:conformsTo`.

Folio still reads `owl:imports` in the ontologies you install, and never edits them. At install, each `owl:imports` becomes a `requires` plus a `prof:isProfileOf`, so an umbrella ontology such as [FIBO](https://spec.edmcouncil.org/fibo/) arrives as an umbrella profile.

## Files: how far the scope reaches

A file may use the terms of the datasets that hold it, of the profiles it conforms to, and of every profile those build on. Its profiles come from the first of these that names any, as [How profiles work](https://semvia.io/docs/modeling/how-profiles-work#where-a-file-gets-its-profile) sets out:

1. The file's own `dct:conformsTo`.
2. The `dct:conformsTo` of the dataset that holds it, the nearest one that claims it.
3. The `conformsTo` in the root `sem.json`.

In the example, `fleet/desert-ridge.ttl` names no profile of its own, so it takes its dataset's: Dataset and Package from Fleet before the fix, and both Plants and Dataset and Package after it.

Typeahead offers the file's own terms first, then its dataset's, then those of the profiles it conforms to, then those of the profiles they build on, and anything that would warn last.

[Next: How profiles work](https://semvia.io/docs/modeling/how-profiles-work): What a profile is, where a file gets one, and what the Profile menu shows and changes.
