# Publish and install a package

> Package a domain model as a semantic package, publish a version of it to an S3-compatible bucket, and install a published version in another workspace by its IRI.

Source: https://semvia.io/docs/quickstart/publish-and-install-a-package

A semantic package works exactly like other packages you might be familiar with in [npm](https://docs.npmjs.com/about-packages-and-modules), [pip](https://packaging.python.org/en/latest/tutorials/packaging-projects/) or [Cargo](https://doc.rust-lang.org/cargo/): a manifest (`sem.json`) describes the package, a collection of files, which is bundled up and published to a registry. After that any other workspace that has access to the registry can add it as a dependency and leverage its contents.

| Folio | Familiar as |
| --- | --- |
| `sem.json` | `package.json`, `pyproject.toml`, `Cargo.toml` |
| `requires` in `sem.json` | `dependencies`. Each entry names a minimum version, and Folio picks versions by [minimal version selection](https://go.dev/ref/mod#minimal-version-selection), as Go does. |
| `sem.sum.json` | Go's [`go.sum`](https://go.dev/ref/mod#go-sum-files): the digest of each version the workspace resolved. Folio recomputes the versions from `requires` each time, so it isn't a lockfile. |
| `imports/` | `node_modules`, `site-packages` |
| **Publish Package** | `npm publish`, `cargo publish`, with your bucket as the registry |
| A published version | Immutable, as on npm, PyPI and crates.io |

What differs is what a package carries: a semantic package carries a piece of a graph. An installed package's graph loads into the workspace, so any operations on the workspace read it along with your own files. [Open world and scope](https://semvia.io/docs/modeling/open-world-and-scope#how-other-languages-work) maps each level of a workspace to Cargo, Go, Maven and pnpm.

This quickstart uses the API of the [Global Legal Entity Identifier Foundation](https://www.gleif.org/) (GLEIF), which publishes the [Legal Entity Identifier](https://www.gleif.org/en/about-lei/introducing-the-legal-entity-identifier-lei) (LEI), a code that identifies a company in financial transactions. This quickstart builds on the connection to that API from [Query a JSON API](https://semvia.io/docs/federation/query-a-json-api) and [Query a database](https://semvia.io/docs/federation/query-a-database) and adds a legal entity class and Internationalized Resource Identifiers (IRIs), the web addresses that identify each legal entity. It packages the result as `semvia/gleif-api` and publishes version 0.1.0 to a bucket. It then installs the 0.1.0 that Semvia published at `pkg.semvia.io` in a second workspace and asks it who ultimately owns a company.

## Before you start

To publish, you need an S3-compatible bucket you can write to, such as [Amazon S3](https://aws.amazon.com/s3/) or [Cloudflare R2](https://developers.cloudflare.com/r2/), and an access key ID and secret access key for it. Installing needs neither: step 4 installs the version Semvia published.

## 1. Make the package

A workspace is a package once its `sem.json` names and versions it. Open **Packages**. It lists your workspace's package under **Workspace packages**. Select its row to open the package editor, and fill in these fields, which Folio writes into `sem.json`:

- **Title** — `GLEIF API`. The name shown in **Packages**.
- **Version** — `0.1.0`. The version the next publish uploads.
- **Base IRI** — `https://pkg.semvia.io/semvia/gleif-api/`, the base IRI Semvia published 0.1.0 under. Where the package's terms live and how other workspaces install it. A package of your own takes a base IRI under a domain you control, and the IRIs in its files follow it.
- **Owner** — `Semvia`. Who publishes the package.
- **Description** — `Reads the GLEIF API live: legal entities by name or LEI, and the company that ultimately owns each.`

Figure: The package editor under Workspace packages: GLEIF API 0.1.0, with Build Package and Publish Package. Title: GLEIF API. Version: 0.1.0. Base IRI: https://pkg.semvia.io/semvia/gleif-api/. Publish destination: Not set, with Set up destination. Default profiles: No default. Owner: Semvia. Description: Reads the GLEIF API live: legal entities by name or LEI, and the company that ultimately owns each.

The package editor with the GLEIF API's fields filled in. Publish destination stays unset until step 3.

All files are swept into the workspace by default. [Open world and scope](https://semvia.io/docs/modeling/open-world-and-scope#datasets-are-the-scope-unit) covers how a package, its datasets and its profiles relate.

Select **New file** in the Explorer, pick **Turtle**, name the file `schema.ttl`, and paste this [Turtle](https://www.w3.org/TR/turtle/) class schema into it. Its property constraints are written in the [Shapes Constraint Language](https://www.w3.org/TR/shacl/) (SHACL), the standard for rules a graph must meet:

Turtle

```turtle
@prefix :       <https://pkg.semvia.io/semvia/gleif-api/schema#> .
@prefix dct:    <http://purl.org/dc/terms/> .
@prefix rdfs:   <http://www.w3.org/2000/01/rdf-schema#> .
@prefix schema: <https://schema.org/> .
@prefix sh:     <http://www.w3.org/ns/shacl#> .
@prefix svs:    <https://pkg.semvia.io/semvia/core/meta-schema#> .
@prefix xsd:    <http://www.w3.org/2001/XMLSchema#> .

<> dct:conformsTo <https://pkg.semvia.io/semvia/core/profiles/class-schema> .

# A legal entity: an organization GLEIF registers under a Legal Entity Identifier.
# Each has one LEI and one legal name, and may name the country of its legal
# address and the company that ultimately owns it.
:LegalEntity a svs:ClassSchema ;
  rdfs:label "Legal entity"@en ;
  rdfs:comment
    "An organization registered with GLEIF under a Legal Entity Identifier."@en ;
  sh:property [
    sh:path schema:leiCode ;
    sh:name "LEI"@en ;
    sh:datatype xsd:string ;
    sh:minCount 1 ;
    sh:maxCount 1 ;
    sh:description "The 20-character Legal Entity Identifier (ISO 17442)."@en
  ], [
    sh:path schema:legalName ;
    sh:name "Legal name"@en ;
    sh:datatype xsd:string ;
    sh:minCount 1 ;
    sh:maxCount 1 ;
    sh:description "The name the entity is registered under."@en
  ], [
    sh:path schema:addressCountry ;
    sh:name "Country"@en ;
    sh:datatype xsd:string ;
    sh:maxCount 1 ;
    sh:description "The ISO 3166-1 alpha-2 code of the legal address's country."@en
  ], [
    sh:path schema:parentOrganization ;
    sh:name "Ultimate parent"@en ;
    sh:class :LegalEntity ;
    sh:maxCount 1 ;
    sh:description
      "The highest-level entity that consolidates this one's accounts."@en
  ] .
```

Graph

Figure: schema.ttl in Graph View. Legal entity, a Class Schema, carries its comment and four instance properties: Country, a string, 0..1; Legal name, a string, 1..1; LEI, a string, 1..1; and Ultimate parent, a Legal entity, 0..1.

A legal entity has one LEI and one legal name, and may name its country and its ultimate parent.

Create `api.ttl` and paste in the connection. It holds a [Thing Description](https://www.w3.org/TR/wot-thing-description11/), which documents the API's endpoints, and an [RDF Mapping Language](https://rml.io/specs/rml/) (RML) mapping, which turns each API response into entities. [Query a JSON API](https://semvia.io/docs/federation/query-a-json-api) covers both. Each legal entity's IRI is `https://gleif.org/lei/` followed by its LEI, so an entity has the same IRI whichever endpoint returns it, and the ultimate-parent link joins the two records.

Turtle

```turtle
@prefix :           <https://pkg.semvia.io/semvia/gleif-api/api#> .
@prefix dct:        <http://purl.org/dc/terms/> .
@prefix gleif:      <https://pkg.semvia.io/semvia/gleif-api/schema#> .
@prefix hctl:       <https://www.w3.org/2019/wot/hypermedia#> .
@prefix htv:        <http://www.w3.org/2011/http#> .
@prefix jsonschema: <https://www.w3.org/2019/wot/json-schema#> .
@prefix rml:        <http://w3id.org/rml/> .
@prefix schema:     <https://schema.org/> .
@prefix svdb:       <https://pkg.semvia.io/semvia/rml/connection#> .
@prefix td:         <https://www.w3.org/2019/wot/td#> .

# Folio checks this file as a Web of Things description and as an RML mapping.
<> dct:conformsTo
    <https://pkg.semvia.io/semvia/core/profiles/web-of-things> ,
    <https://pkg.semvia.io/semvia/rml/profiles/rml-mapping> .

# The GLEIF API, and the three properties this package reads.
:api a td:Thing ;
  td:title "GLEIF API" ;
  td:baseURI "https://api.gleif.org/api/v1/" ;
  td:hasPropertyAffordance :leiRecords, :leiRecord, :ultimateParent .

# The LEI records, which GLEIF can filter by legal name: the request to send,
# and the fields of each record in the response that the mappings below read.
:leiRecords a td:PropertyAffordance, jsonschema:ObjectSchema ;
  td:name "leiRecords" ;
  td:hasUriTemplateSchema [
    a jsonschema:StringSchema ;
    td:name "filter%5Bentity.legalName%5D"
  ] ;
  td:hasForm [
    a hctl:Form ;
    hctl:hasTarget "lei-records?page%5Bsize%5D=100{&filter%5Bentity.legalName%5D}" ;
    htv:methodName "GET" ;
    hctl:forContentType "application/vnd.api+json"
  ] ;
  jsonschema:properties [
    a jsonschema:ArraySchema ;
    jsonschema:propertyName "data" ;
    td:description "The LEI records that match the request." ;
    jsonschema:items [
      a jsonschema:ObjectSchema ;
      jsonschema:properties [
        a jsonschema:ObjectSchema ;
        jsonschema:propertyName "attributes" ;
        td:description "What GLEIF registers for one LEI." ;
        jsonschema:properties [
          a jsonschema:StringSchema ;
          jsonschema:propertyName "lei" ;
          td:description "The 20-character Legal Entity Identifier (ISO 17442)."
        ], [
          a jsonschema:ObjectSchema ;
          jsonschema:propertyName "entity" ;
          td:description "The legal entity the LEI identifies." ;
          jsonschema:properties [
            a jsonschema:ObjectSchema ;
            jsonschema:propertyName "legalName" ;
            td:description "The registered legal name and its language." ;
            jsonschema:properties [
              a jsonschema:StringSchema ;
              jsonschema:propertyName "name" ;
              td:description "The name as recorded in the entity's registration."
            ]
          ], [
            a jsonschema:ObjectSchema ;
            jsonschema:propertyName "legalAddress" ;
            td:description "The address the entity registered in its jurisdiction." ;
            jsonschema:properties [
              a jsonschema:StringSchema ;
              jsonschema:propertyName "country" ;
              td:description "The ISO 3166-1 alpha-2 code of that address's country."
            ]
          ]
        ]
      ]
    ]
  ] .

# The record of the legal entity with a given LEI: the request to send, and
# the fields of the record in the response that the mapping below reads.
:leiRecord a td:PropertyAffordance, jsonschema:ObjectSchema ;
  td:name "leiRecord" ;
  td:hasUriTemplateSchema [
    a jsonschema:StringSchema ;
    td:name "lei"
  ] ;
  td:hasForm [
    a hctl:Form ;
    hctl:hasTarget "lei-records/{lei}" ;
    htv:methodName "GET" ;
    hctl:forContentType "application/vnd.api+json"
  ] ;
  jsonschema:properties [
    a jsonschema:ObjectSchema ;
    jsonschema:propertyName "data" ;
    td:description "The LEI record for the requested LEI." ;
    jsonschema:properties [
      a jsonschema:ObjectSchema ;
      jsonschema:propertyName "attributes" ;
      td:description "What GLEIF registers for the LEI." ;
      jsonschema:properties [
        a jsonschema:StringSchema ;
        jsonschema:propertyName "lei" ;
        td:description "The 20-character Legal Entity Identifier (ISO 17442)."
      ], [
        a jsonschema:ObjectSchema ;
        jsonschema:propertyName "entity" ;
        td:description "The legal entity the LEI identifies." ;
        jsonschema:properties [
          a jsonschema:ObjectSchema ;
          jsonschema:propertyName "legalName" ;
          td:description "The registered legal name and its language." ;
          jsonschema:properties [
            a jsonschema:StringSchema ;
            jsonschema:propertyName "name" ;
            td:description "The name as recorded in the entity's registration."
          ]
        ], [
          a jsonschema:ObjectSchema ;
          jsonschema:propertyName "legalAddress" ;
          td:description "The address the entity registered in its jurisdiction." ;
          jsonschema:properties [
            a jsonschema:StringSchema ;
            jsonschema:propertyName "country" ;
            td:description "The ISO 3166-1 alpha-2 code of that address's country."
          ]
        ]
      ]
    ]
  ] .

# The company that ultimately owns the legal entity with a given LEI: the
# request to send, and the two LEIs in the response that the mapping reads.
:ultimateParent a td:PropertyAffordance, jsonschema:ObjectSchema ;
  td:name "ultimateParent" ;
  td:hasUriTemplateSchema [
    a jsonschema:StringSchema ;
    td:name "lei"
  ] ;
  td:hasForm [
    a hctl:Form ;
    hctl:hasTarget "lei-records/{lei}/ultimate-parent-relationship" ;
    htv:methodName "GET" ;
    hctl:forContentType "application/vnd.api+json"
  ] ;
  jsonschema:properties [
    a jsonschema:ObjectSchema ;
    jsonschema:propertyName "data" ;
    td:description "The ultimate-parent relationship recorded for the LEI." ;
    jsonschema:properties [
      a jsonschema:ObjectSchema ;
      jsonschema:propertyName "attributes" ;
      td:description "What GLEIF records about the relationship." ;
      jsonschema:properties [
        a jsonschema:ObjectSchema ;
        jsonschema:propertyName "relationship" ;
        td:description "The child entity and the parent that consolidates it." ;
        jsonschema:properties [
          a jsonschema:ObjectSchema ;
          jsonschema:propertyName "startNode" ;
          td:description "The child entity, whose LEI was requested." ;
          jsonschema:properties [
            a jsonschema:StringSchema ;
            jsonschema:propertyName "id" ;
            td:description "The child entity's LEI."
          ]
        ], [
          a jsonschema:ObjectSchema ;
          jsonschema:propertyName "endNode" ;
          td:description "The ultimate parent." ;
          jsonschema:properties [
            a jsonschema:StringSchema ;
            jsonschema:propertyName "id" ;
            td:description "The ultimate parent's LEI."
          ]
        ]
      ]
    ]
  ] .

# Each record GLEIF returns for a legal name. A query that names a legal
# name asks GLEIF for that one only.
:recordsByName a rml:LogicalSource ;
  rml:source :leiRecords ;
  rml:referenceFormulation rml:JSONPath ;
  rml:iterator "$.data[*]" ;
  svdb:fillsVariable [
    a svdb:VariableFill ;
    svdb:variableName "filter%5Bentity.legalName%5D" ;
    svdb:selectsReference "attributes.entity.legalName.name"
  ] .

# The record GLEIF holds for one LEI.
:recordByLei a rml:LogicalSource ;
  rml:source :leiRecord ;
  rml:referenceFormulation rml:JSONPath ;
  rml:iterator "$.data" ;
  svdb:fillsVariable [
    a svdb:VariableFill ;
    svdb:variableName "lei" ;
    svdb:selectsReference "attributes.lei"
  ] .

# The ultimate-parent relationship GLEIF records for one LEI.
:parentLink a rml:LogicalSource ;
  rml:source :ultimateParent ;
  rml:referenceFormulation rml:JSONPath ;
  rml:iterator "$.data" ;
  svdb:fillsVariable [
    a svdb:VariableFill ;
    svdb:variableName "lei" ;
    svdb:selectsReference "attributes.relationship.startNode.id"
  ] .

# Turns each record found by legal name into a legal entity.
:ByNameMap a rml:TriplesMap ;
  rml:logicalSource :recordsByName ;
  rml:subjectMap [
    rml:template "https://gleif.org/lei/{attributes.lei}" ;
    rml:class gleif:LegalEntity
  ] ;
  rml:predicateObjectMap [
    rml:predicate schema:leiCode ;
    rml:objectMap [ rml:reference "attributes.lei" ]
  ], [
    rml:predicate schema:legalName ;
    rml:objectMap [ rml:reference "attributes.entity.legalName.name" ]
  ], [
    rml:predicate schema:addressCountry ;
    rml:objectMap [ rml:reference "attributes.entity.legalAddress.country" ]
  ] .

# Turns the record for one LEI into a legal entity.
:ByLeiMap a rml:TriplesMap ;
  rml:logicalSource :recordByLei ;
  rml:subjectMap [
    rml:template "https://gleif.org/lei/{attributes.lei}" ;
    rml:class gleif:LegalEntity
  ] ;
  rml:predicateObjectMap [
    rml:predicate schema:leiCode ;
    rml:objectMap [ rml:reference "attributes.lei" ]
  ], [
    rml:predicate schema:legalName ;
    rml:objectMap [ rml:reference "attributes.entity.legalName.name" ]
  ], [
    rml:predicate schema:addressCountry ;
    rml:objectMap [ rml:reference "attributes.entity.legalAddress.country" ]
  ] .

# Links each legal entity to the company that ultimately owns it.
:UltimateParentMap a rml:TriplesMap ;
  rml:logicalSource :parentLink ;
  rml:subjectMap [
    rml:template "https://gleif.org/lei/{attributes.relationship.startNode.id}" ;
    rml:class gleif:LegalEntity
  ] ;
  rml:predicateObjectMap [
    rml:predicate schema:parentOrganization ;
    rml:objectMap [
      rml:template "https://gleif.org/lei/{attributes.relationship.endNode.id}"
    ]
  ] .
```

Graph

Figure: api.ttl in Graph View. GLEIF API, a WoT Thing with three properties, base URI https://api.gleif.org/api/v1/ and a data schema for each, links by hasPropertyAffordance to three endpoints, each a WoT Object Schema and WoT Property Affordance whose card lists its response. GET lei-records with the legal-name filter returns data, an array of records; GET lei-records/{lei} returns data, one record. In each record, attributes holds lei and entity, and entity holds legalAddress, with country, and legalName, with name; each is a string. GET lei-records/{lei}/ultimate-parent-relationship returns data, whose attributes hold relationship, with the id of its startNode and its endNode. Three LogicalSources link by source to those endpoints: recordsByName iterates $.data[*], and recordByLei and parentLink read $.data. Lines run from each field a source reads to that field in the response, and each lists the variable it fills. ByNameMap and ByLeiMap read the first two and make each record a Legal entity, with lines from their addressCountry, legalName and leiCode rows to the Country, Legal name and LEI properties on the Legal entity card from schema.ttl. UltimateParentMap reads parentLink, makes the startNode a Legal entity, and links it by parentOrganization to its ultimate parent, with a line to the Ultimate parent property.

Each endpoint describes the response it returns, and each logical source reads its fields; ByNameMap and ByLeiMap make legal entities, and UltimateParentMap links each to its ultimate parent.

Each file names its profile with `dct:conformsTo`, and **Problems** lists nothing.

## 2. Build the package

In **Packages**, select **Build Package** on the GLEIF API row. Folio builds the package into `built/` and shows "Built GLEIF API."

## 3. Publish version 0.1.0

Publishing uploads an archive of the package to your bucket, so first tell Folio where the bucket is. In the package editor, under **Publish destination**, select **Set up destination**, then **S3-compatible bucket**, and fill in your bucket:

- **Bucket** — The bucket's name, such as `acme-packages`.
- **Region** — The bucket's region, such as `eu-west-1`. Cloudflare R2 takes `auto`.
- **Endpoint** — Your provider's S3 endpoint, such as `https://your-account-id.r2.cloudflarestorage.com` for Cloudflare R2. Leave it empty for Amazon S3.
- **Key prefix** — Where in the bucket the package's versions go, such as `semvia/gleif-api/`.

**Uploads to** shows the key each version goes to. Select **Save**, and Folio writes the destination into `sem.json` as `publishTo`.

The card now asks for the bucket's access key, which your provider issues for the bucket as an access key ID and a secret access key. Select **Bind access key…** and bind the secret access key, in any store [Add credentials](https://semvia.io/docs/federation/credentials) describes. Select **Bind access key…** again and bind the access key ID. Select **Test connection**, and the card shows **Connection OK**.

In **Packages**, select **Publish Package** on the GLEIF API row. The **Publish package** dialog rehearses the build, then shows the package's base IRI, name and version, **Never published** for a first version, the **Destination**, and **Will publish**: the archive, `0.1.0.sem.tgz`, and each file in it. Select **Dry run** to rehearse the publish without uploading.

Figure: The Publish package dialog for https://pkg.semvia.io/semvia/gleif-api/, gleif-api 0.1.0, Never published. Destination: Blob, semvia-pkg at an r2.cloudflarestorage.com endpoint. Will publish: 0.1.0.sem.tgz, 4.0 kB, holding sem.json, api.ttl, schema.ttl, and built/api.ttl, built/index.jsonld and built/schema.ttl. Buttons: Dry run, Cancel and Publish 0.1.0.

The first publish of gleif-api: the bucket it goes to, and the archive with the three files at the top of the workspace and the three Folio built.

Select **Publish 0.1.0**, and Folio uploads the archive to the key **Uploads to** showed. The dialog then shows **Published gleif-api 0.1.0.**, the archive's digest, the address it was uploaded to, and the IRI it resolves as. A published version is never replaced: to publish a change, raise **Version** in the package editor and publish again.

**Git repository** is the other destination. It publishes a version as a tag in a [git](https://git-scm.com/) checkout of the workspace, and the checkout needs at least one commit; you push the tag with your own `git`.

## 4. Install the package

Now install the package the way any other workspace would. This step uses the 0.1.0 that Semvia published, so it works without a bucket of your own.

In a new workspace, open **Packages** and select **Add Dependency**. In the **Add dependency** dialog, paste this into **Install a package**:

```
https://pkg.semvia.io/semvia/gleif-api/@0.1.0
```

Select **Install package**. Folio downloads the archive, adds the package to `requires` in `sem.json`, records its digest in `sem.sum.json`, and unpacks it under `imports/`. [Open world and scope](https://semvia.io/docs/modeling/open-world-and-scope#workspaces-and-semantic-packages) covers what installing a package does and doesn't put in scope.

Figure: Packages: 1 package, 1 dependency. Workspace packages lists the new workspace's own package, gleif-consumer-main, at 0.0.0. Resolved dependencies lists https://pkg.semvia.io/semvia/gleif-api/ at 0.1.0.

**Packages** lists the installed package under Resolved dependencies, at 0.1.0.

Select **New file**, pick **SPARQL Query**, name the file `ultimate-parent.rq`, and paste in this query, written in [SPARQL](https://www.w3.org/TR/sparql11-query/), the standard query language for graphs. Select **Run**.

```sparql
PREFIX schema: <https://schema.org/>

SELECT ?parent WHERE {
  # The company GLEIF records as Hand Held Products' ultimate parent
  <https://gleif.org/lei/549300XSSOVXUBYXG862> schema:parentOrganization ?entity .
  # and the legal name that company is registered under.
  ?entity schema:legalName ?parent .
}
```

The installed mapping asks GLEIF for Hand Held Products' ultimate-parent relationship, then for the parent's record.

Figure: The Results tab: 1 row. Column parent. Row: HONEYWELL INTERNATIONAL INC.

HONEYWELL INTERNATIONAL INC. is the company GLEIF records as Hand Held Products' ultimate parent.

[Next: Query your data with SPARQL](https://semvia.io/docs/quickstart/query-your-data-with-sparql): Write SPARQL over the NYC taxi zones: filter and sort, join two data files, keep rows with OPTIONAL, and count and add up.
