Crate curies

Expand description

§ℹ️ Introduction

A cross-platform library for idiomatic conversion between URIs and compact URIs (CURIEs).

Uniform resource identifiers (URIs) and compact URIs (CURIEs) have become the predominant syntaxes for identifying concepts in linked data applications. Therefore, efficient, faultless, and idiomatic conversion between them is a crucial low-level utility whose need is ubiquitous across many codebases.

curies fills this need. This cross-platform package can be used by a variety of people:

Data Scientist - someone who consumes and modifies data to suit an analysis or application. For example, they might want to convert tabular data containing CURIEs into IRIs, translate into RDF, then query with SPARQL.
Curator - someone who creates data. For example, an ontologist may want to curate using CURIEs but have their toolchain 1) validate the syntax and semantics and 2) convert to IRIs for their data persistence
Data Consumer - someone who consumes data. This kind of user likely won’t interact with curies directly, but will likely use tools that build on top of it. For example, someone using the Bioregistry resolution service uses this package’s expansion utilities indirectly.
Software Developer - someone who develops tools to support data creators, data consumers, and other software developers. For example, a software developer might want to make their toolchain more generic for loading, merging, and outputting prefix maps and extended prefix maps.

For many users, expansion (CURIE to URI) and contraction (URI to CURIE) are the two most important tools. Example:

CURIE	URI
`doid:1234`	http://purl.obolibrary.org/obo/DOID_1234

§✨ Features

📥 Import converters from JSON prefix maps or JSON-LD context, with helper functions for popular converters, such as get_obo_converter(), or create a custom converter programmatically.
🔗 Expand CURIEs from their compressed form to URIs.
🗜️ Compress URIs to CURIEs.
🧩 Standardize prefixes, CURIEs, or URIs.

§📦️ Packaged for multiple interfaces

This library is packaged for easy use across various interfaces and languages:

🦀 Rust developers: available as a Rust crate curies
🐍 Python programmers: available as a Python pip package curies-rs
🌐 JavaScript web developers: available as a NPM package @biopragmatics/curies, compiled to WebAssembly, for browser integrations with JavaScript, or NodeJS.
📈 R data scientists: soon available as a R package curies

§⚔️ Cross-platform support

It runs seamlessly on x86 and ARM architectures for many platforms:

🐧 Linux
🍎 MacOS
🪟 Windows
🦊 Web browsers

💡 Need Help or Have Suggestions? We welcome your input and feedback! If you encounter any issues or have ideas to enhance this tool, please create an issue on our GitHub repository.

§🦀 Use from Rust

§📥️ Installation

cargo add curies

§🚀 Usage

You can use the Rust crate to work with CURIEs: import converters, compress URIs, expand CURIEs.

use curies::{Converter, Record, sources::get_bioregistry_converter};
use std::collections::HashSet;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {

    // Load from a prefix map json (string or URI)
    let converterFromMap = Converter::from_prefix_map(r#"{
  "doid": "http://purl.obolibrary.org/obo/MY_DOID_"
}"#).await?;

    // Load from an extended prefix map (string or URI)
    let converterFromUrl = Converter::from_extended_prefix_map("https://w3id.org/biopragmatics/bioregistry.epm.json").await?;

    // Load from a JSON-LD context (string or URI)
    let converterFromJsonld = Converter::from_jsonld("https://purl.obolibrary.org/meta/obo_context.jsonld").await?;

    // Load from one of the predefined source
    let converterFromSource = get_bioregistry_converter().await?;

    // Chain multiple converters in one
    let converter = Converter::chain(vec![converterFromMap, converterFromUrl, converterFromSource])?;

    let uri = converter.expand("doid:1234")?;
    println!("Expanded CURIE: {}", uri);

    let curie = converter.compress("http://purl.obolibrary.org/obo/DOID_1234")?;
    println!("Compressed URI: {}", curie);
    Ok(())
}

And

use curies::sources::get_bioregistry_converter;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let converter = get_bioregistry_converter().await?;

    let epm = converter.write_extended_prefix_map()?;
    let pm = converter.write_prefix_map();
    let jsonld = converter.write_jsonld();
    let shacl = converter.write_shacl()?;
    Ok(())
}

§🛠️ Manipulate converters and records

You can also build a Converter programmatically from Record structs:

extern crate curies;
use curies::{Converter, Record};
use std::collections::HashSet;

fn build_example() -> Result<(), Box<dyn std::error::Error>> {
    let mut converter = Converter::default();

    let record1 = Record {
        prefix: "doid".to_string(),
        uri_prefix: "http://purl.obolibrary.org/obo/DOID_".to_string(),
        prefix_synonyms: HashSet::from(["DOID".to_string()]),
        uri_prefix_synonyms: HashSet::from(["https://identifiers.org/DOID/"].map(String::from)),
        pattern: None,
    };
    let record2 = Record::new("obo", "http://purl.obolibrary.org/obo/");
    converter.add_record(record1)?;
    converter.add_record(record2)?;

    let uri = converter.expand("doid:1234")?;
    println!("Expanded CURIE: {}", uri);

    let curie = converter.compress("http://purl.obolibrary.org/obo/DOID_1234")?;
    println!("Compressed URI: {}", curie);
    Ok(())
}
build_example().unwrap();

§📖 API reference

Checkout the API documentation for more details on how to use the different components and functions of the rust crate.

Re-exports§

pub use api::Converter;
pub use api::Record;
pub use error::CuriesError;

Modules§

api
API for Converter and Record
error
Errors thrown by the library
fetch
Traits and functions for fetching data from HTTP or file system
sources
Contains functions for getting pre-defined contexts

Crate curiesCopy item path