@neverblink/linkml 0.13.1 → 0.15.0

package/README.md

@@ -76,13 +76,15 @@ Load a schema into a `SchemaView` handle (see above), then pass that handle to a
 | `loadFromString(schema, importMap, inferMessages?)`                  | `LoadResult` | parse from YAML text; `{ view?, report }`                    |
 | `loadFromPath(path, importMap, inferMessages?)`                      | `LoadResult` | parse from a path in the import map; cycle-safe for the root |
 | `jsonSchema(view, open?, treeRootOverride?)`                         | `string` | JSON Schema                                                  |
-| `shacl(view, open?, onlyClassesFromRootSchema?)`                     | `string` | SHACL shapes in N-Triples                                    |
-| `rdfs(view, onlyClassesFromRootSchema?)`                             | `string` | RDFS in N-Triples                                            |
+| `shacl(view, open?, onlyClassesFromRootSchema?, format?)`            | `string` | SHACL shapes, `ttl` (default) or `nt`                        |
+| `rdfs(view, onlyClassesFromRootSchema?, format?)`                    | `string` | RDFS, `ttl` (default) or `nt`                                |
 | `linkml(view, pruningMode?, skipDerivation?, treeRoot?, outFormat?)` | `string` | derived/pruned LinkML schema                                 |
 | `scala(view, packageName)`                                           | `Record<string, string>` | filename → generated Scala                                   |
-| `tableSchema(view, treeRoot?)`                                       | `string` | Frictionless Table Schema (JSON)                             |
+| `frictionless(view, pruningMode?, treeRoot?, skipClassesWithoutIdentifier?)` | `Record<string, string>` | filename → Frictionless data package (`datapackage.json` and `schemas/*.json`) |
 | `graphQl(view, pruningMode?, treeRoot?)`                             | `string` | GraphQL                                                      |
+| `erDiagram(view, pruningMode?, treeRoot?, optionalMarker?)`          | `string` | Mermaid entity relationship diagram                          |
 | `lint(view, inferMessages?)`                                         | `object` | `SchemaValidationReport` (JSON)                              |
+| `buildInfo()`                                                        | `object` | `BuildInfo` (JSON) – version and build metadata |
 
 See [`index.d.ts`](./index.d.ts) for full type signatures.
 

package/index.d.ts

@@ -22,7 +22,13 @@ export interface LoadResult {
 
 export interface LinkMLApi {
   /**
-   * Load and resolve a LinkML schema into a reusable [[SchemaView]] handle, starting from the schema's YAML text.  The main schema is parsed directly from `mainSchema`, so it has no path of its own. If one of its imports (transitively) imports the main schema back by filename, that import cannot be matched against the root and the main schema will be loaded a second time. Use [[loadFromPath]] instead when the root schema takes part in an import cycle.
+   * Version and build metadata of this copy of LinkML-Scala: which version it is, which LinkML metamodel it was built against, and what it is running on.  Useful in bug reports, and for checking that the version you loaded is the one you meant to.
+   * @returns A `BuildInfo` object, as described by https://linkml.neverblink.eu/model/build-info
+   */
+  buildInfo(): any;
+
+  /**
+   * Load and resolve a LinkML schema into a reusable [[SchemaView]] handle, starting from the schema's YAML text.  The main schema is parsed directly from `mainSchema`, so it has no path of its own. If one of its imports (transitively) imports the main schema back by filename, that import cannot be matched against the root and the main schema will be loaded a second time. Use [[loadFromPath]] instead when the root schema takes part in an import cycle.  See [[loadFromPath]] for the correct key format.
    * @param mainSchema Main LinkML model in YAML format. It may import other models using LinkML `imports`, but all imports must be made available in the [[importMap]].
    * @param importMap JS dictionary (object) containing a mapping from filename to LinkML models (in YAML format)
    * @param inferMessages Whether to fill in each issue's human-readable `message` and `details`.
@@ -31,7 +37,7 @@ export interface LinkMLApi {
   loadFromString(mainSchema: string, importMap: Record<string, string>, inferMessages?: boolean): LoadResult;
 
   /**
-   * Load and resolve a LinkML schema into a reusable [[SchemaView]] handle, starting from a path into the [[importMap]].  Unlike [[loadFromString]], the main schema is read through the import map by its own path, so it is tracked from the start of import resolution. This makes it immune to cyclic imports involving the root schema: an import that (transitively) references the root back by path resolves to the already-loaded root instead of loading it again.  Paths behave like file paths: a `.yaml` extension is appended when missing, and relative imports are resolved against the directory of their importing schema. The [[importMap]] keys must therefore be the paths as seen from the root (e.g. `"model.yaml"`, `"nested/person.yaml"`).
+   * Load and resolve a LinkML schema into a reusable [[SchemaView]] handle, starting from a path into the [[importMap]].  Unlike [[loadFromString]], the main schema is read through the import map by its own path, so it is tracked from the start of import resolution. This makes it immune to cyclic imports involving the root schema: an import that (transitively) references the root back by path resolves to the already-loaded root instead of loading it again.  Keys in the ``imports`` parameter must match the expanded form of the ``imports`` entries in the schema. In particular:  - A CURIE is expanded through the schema's prefix map, so ``imports: [ex:core]`` has to be keyed here by the full URI, such as ``"https://example.org/core.yaml"``. - A relative import is joined to the directory of the schema that imported it, so a ``core`` imported by ``nested/model.yaml`` has to be keyed ``"nested/core.yaml"``. Keys are therefore paths as seen from the root. - ``.yaml`` is appended unless the path already ends in ``.yaml`` or ``.yml``. Therefore, ``"core"`` and ``"core.yaml"`` are interchangeable, and a key that ends in ``.yml`` is only found by an import that explicitly asks for ``.yml``.
    * @param path Path of the main LinkML model within the [[importMap]] (e.g. `"model.yaml"`).
    * @param importMap JS dictionary (object) containing a mapping from path to LinkML models (in YAML format), including the main schema itself under [[path]].
    * @param inferMessages Whether to fill in each issue's human-readable `message` and `details`.
@@ -49,13 +55,14 @@ export interface LinkMLApi {
   jsonSchema(schema: SchemaView, open?: boolean, treeRootOverride?: string): string;
 
   /**
-   * Generate SHACL shapes (in N-Triples format) from a loaded LinkML schema.
+   * Generate SHACL shapes from a loaded LinkML schema.
    * @param schema A [[SchemaView]] handle created with [[loadFromString]] or [[loadFromPath]].
    * @param open Whether the SHACL shapes should be open (`_:b sh:closed false .`, allowing additional properties).
    * @param onlyClassesFromRootSchema Whether to include only classes from the root schema (turned off by default). This is useful if you intend to generate SHACL shapes for each schema file separately, and you don't need the imported classes to be included in the generated SHACL shapes.
-   * @returns SHACL shapes in N-Triples format
+   * @param format RDF serialization format: `ttl` for Turtle (the default), which is prefixed and pretty-printed, or `nt` for N-Triples.
+   * @returns SHACL shapes in the requested format
    */
-  shacl(schema: SchemaView, open?: boolean, onlyClassesFromRootSchema?: boolean): string;
+  shacl(schema: SchemaView, open?: boolean, onlyClassesFromRootSchema?: boolean, format?: string): string;
 
   /**
    * Generate Scala code from a loaded LinkML schema. This is primarily used for the metamodel
@@ -69,9 +76,10 @@ export interface LinkMLApi {
    * Generate RDFS from a loaded LinkML schema.
    * @param schema A [[SchemaView]] handle created with [[loadFromString]] or [[loadFromPath]].
    * @param onlyClassesFromRootSchema Whether to include only classes from the root schema (turned off by default). This is useful if you intend to generate SHACL shapes for each schema file separately, and you don't need the imported classes to be included in the generated SHACL shapes.
-   * @returns RDFS in N-Triples format
+   * @param format RDF serialization format: `ttl` for Turtle (the default), which is prefixed and pretty-printed, or `nt` for N-Triples.
+   * @returns RDFS in the requested format
    */
-  rdfs(schema: SchemaView, onlyClassesFromRootSchema?: boolean): string;
+  rdfs(schema: SchemaView, onlyClassesFromRootSchema?: boolean, format?: string): string;
 
   /**
    * Materialize a derived LinkML schema from a loaded LinkML schema. Derives classes and prunes unreachable elements.
@@ -85,12 +93,14 @@ export interface LinkMLApi {
   linkml(schema: SchemaView, pruningMode?: string, skipDerivation?: boolean, treeRoot?: string, outFormat?: string): string;
 
   /**
-   * Generate a Frictionless Table Schema from a loaded LinkML schema.
+   * Generate a Frictionless Data Package from a loaded LinkML schema. Every class becomes a CSV table, described by its own Table Schema, and references between classes become foreign keys between the tables.
    * @param schema A [[SchemaView]] handle created with [[loadFromString]] or [[loadFromPath]].
-   * @param treeRoot Tree root class name to use instead of the schema defined tree_root.
-   * @returns Table Schema, serialized as a JSON
+   * @param pruningMode Pruning mode to use for choosing which classes become tables. One of treeRoot|schema|skip. treeRoot - only classes reachable from the tree_root class. schema - only classes reachable from any of the classes defined in the root schema. skip - every class. Default: skip
+   * @param treeRoot Tree root class name to use instead of the schema defined tree_root. Does nothing if not in tree root pruning mode.
+   * @param skipClassesWithoutIdentifier Whether to skip classes that have no identifier slot. Such a table gets no primary key and nothing can reference it, so it is often not useful. Default: false
+   * @returns JS dictionary (object) containing a mapping from filename to file content: a `datapackage.json` plus one `schemas/<table>.json` per table.
    */
-  tableSchema(schema: SchemaView, treeRoot?: string): string;
+  frictionless(schema: SchemaView, pruningMode?: string, treeRoot?: string, skipClassesWithoutIdentifier?: boolean): Record<string, string>;
 
   /**
    * Generate a GraphQL Schema from a loaded LinkML schema. Only types/interfaces/scalar/enums, queries must be provided for a specific implementation.