# FAR - FHIR Artifact Repository

FAR is a Storage API to serve, distribute and author FHIR [Canonical Resource](https://build.fhir.org/canonicalresource.html) and [FHIR Packages](https://confluence.hl7.org/display/FHIR/NPM+Package+Specification).

It's close to [CRMI](https://build.fhir.org/ig/HL7/crmi-ig/profiles.html), but includes all Canonical Resourca and more IG and package oriented.

FAR defines several roles:

* serving - serve packages content and resources lookups
* resolve references and dependencies
* serve derivatives like JSON & FHIR Schema, GraphQL
* generate SDKs
* authoring - provide API to create, validate and publish packages

## Key Features

* registrtry of all public packages
* resolved deps and refs
* package editor with autocomplete, validation and audit trails
* history and changes API to sinc changing resources
* derivatives FHIR/JSON Schema, GraphQL
* generate SDK
* deployment packages based on CapabilityStatement
* Can handle multiple versions of FHIR

## Canonical Resource

The key artefact of FAR is [Canonical Resource](https://build.fhir.org/canonicalresource.html).

FHIR Canonical Resources are a specific subset of FHIR resources that are intended to be stable. These resources are foundational and define the basic elements of the FHIR specification, including structures for core concepts and data types. They are called "canonical" because they serve as the standard or model upon which other resources and implementations can be based.

Canonical resources include, but are not limited to:

* StructureDefinition: Defines the structure of other resources, including constraints and extensions.
* ValueSet: Defines a set of possible values for a particular element in resources.
* CodeSystem: Provides a collection of codes used in one or more value sets.
* ConceptMap: Relates concepts in one code system to concepts in another.
* NamingSystem: Provides unique identifiers for various items, including systems, value sets, and structures.

The CanonicalResource represents resources that have a canonical URL:

* They have a canonical URL (note: all resources with a canonical URL are specializations of this type)
* They have version, status, and data properties to help manage their publication
* They carry some additional metadata about their use, including copyright information

It has an interface:

{ 
    resourceType: 
    url: 
    version:
    name:
    date:
    status: 
}

### Versions

[Canonical Versions](https://brianpos.com/2023/08/04/deploying-a-fhir-implementation-guide/)

Canonical may have multipe versions, by default version is inherited from package, but in general you may have multiple versions of same canonical in on package.

### FHIR versions

Because every canonical resource may be referenced without fhirVersion, it may/should contain the fhirVersion. Probably in profile - https://hl7.org/fhir/versioning.html#mp-version

### URL template

It is recomended (IG Publisher does it) for canonical to generate URL by following schema:

`package-url-prefix/resourceType/name`

FAR generates urls by this template by default.

### Canonical Resource Identity

The Canonical Resource identity by FHIR is url and version and can be refered with [canonical uri](https://build.fhir.org/datatypes.html#canonical) - `url|version`

But technically different packages may contain same canonical with same version. So Canonical in packages has **package-id** = `package|version|url|version`.

Every resurce is assigned server-id:

Canonical Resource id = `package | package-version | url | version`
Resource id = `package | package-version | resourceType | id`
When you read resource, you see original id and server-id in extension.

{
   resourceType: '...',
   id: 'some-id',
   extension: [{
     url: 'far:server-id', 
     valueString: 'pkg|pkg-version|url|version'
   }]
 // ...
}

## Package

**Package** is a set of FHIR Resources (Canonical and others) with package manifest.

Package may not contain two canonicals with same url and version, or two non-canonical resources with same resourceType and id! That's the only limitation. I.e. it may contain same url canonical of different versions.

[CRMI Package](https://build.fhir.org/ig/HL7/crmi-ig/branches/master/distribution.html)

### Implementation Guide

IG is package with ImplementationGuide resource.

### Package name

[policy](https://confluence.hl7.org/pages/viewpage.action?pageId=35718629#NPMPackageSpecification-Packagename)

Each package has a canonical name (a globally unique identifier). A package name consists of two or more namespaces separated by a dot. Each namespace starts with a lowercase alphabet character followed by zero-or-more lowercase alphanumeric characters or dashes.

The first part of the namespace should identify the author, the authoring organization, or region. The second part of the namespace should identify the functional scope or purpose of the package.

Examples:

* hl7.fhir.core (main build)
* hl7.fhir.r4.core (core package - contains what's needed for validation/IG publication)
* hl7.fhir.r4b.examples (examples in R4B)
* hl7.fhir.us.core

### Package Deps

Packages may depend on other packages. This can be used for
references resolution.

### Package reference resolution

# API

## Package API

* GET /Packages - get list of all packages
* GET /Package/:pkg-name - get all versions of package
* GET /Package/:pkg-name/:pkg-version - get package information
* GET /Package/:pkg-name/:pkg-version/changes - get feed of changes

## Resource in Package API

* GET [pkg]/:canonicalResourceType
* GET [pkg]/:canonicalResourceType/:name - list of canonicals
* PUT [pkg]/:canonicalResourceType/:name - post with default version
* GET [pkg]/:canonicalResourceType/:name/:version
* PUT [pkg]/:canonicalResourceType/:name/:version
* GET [pkg]/:canonicalResourceType/:name/:version/_history
* GET [pkg]/:canonicalResourceType/:name/:version/_history/:revision
* GET [pkg]/:resourceType
* POST [pkg]/:resourceType
* GET [pkg]/:resourceType/:id

TODO:

* Current Canonical - https://build.fhir.org/canonicalresource-operation-current-canonical.html

## Generate SDK

TODO:

## Canonical Resoultion API

* GET /Canonical?url=CanonicalURL

# Deploymnet Packages

Special package built from CapabilityStatement entry point

## Links

* [CRMI]()
* [FHIR npm Package](https://confluence.hl7.org/display/FHIR/NPM+Package+Specification)
* [FHIR Canonical Interface](https://build.fhir.org/canonicalresource.html)
* [Simplifier API](https://app.swaggerhub.com/apis-docs/firely/Simplifier.net_FHIR_Package_API/1.0.1#/default/get_catalog)
* [Brian Post about Canonical Versions](https://brianpos.com/2023/08/04/deploying-a-fhir-implementation-guide/)
* [zulip about package & canonical versions](https://chat.fhir.org/#narrow/stream/179166-implementers/topic/Package.20version.20and.20Canonical.20Resource.20version)