Skip to content

Modeling Open world and scope

New to Folio? Start here

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.

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, 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, Go, Java and TypeScript each settle on roughly four levels:

The unit you…Rust / CargoGoJava / MavenTypeScript / pnpm
CommitWorkspaceWorkspace (go.work)Multi-module buildWorkspace
InstallPackageModule (require)Artifact (dependency)Package (dependencies)
ImportCrate (use)Package (import)Package (import)Subpath export (foo/bar)
EditSource fileSource fileCompilation 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…FolioRust / CargoGoJava / MavenTypeScript / pnpm
CommitWorkspaceWorkspaceWorkspace (go.work)Multi-module buildWorkspace
InstallSemantic package (requires)PackageModule (require)Artifact (dependency)Package (dependencies)
ImportDataset (conformsTo)Crate (use)Package (import)Package (import)Subpath export (foo/bar)
EditFileSource fileSource fileCompilation 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 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 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:

sem.json
{
  "@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:

Workspace
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. 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:

fleet/dataset.ttl
@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:

fleet/desert-ridge.ttl
@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".

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:

plants.rq
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)
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/
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. The dataset-membership rule states it in full.

Profiles define what you use

Every svds:Dataset is also a PROF 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:

fleet/dataset.ttl
@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 is the workspace's base address followed by the file's path, without the extension.

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 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'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:

plants/dataset.ttl
@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 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 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.