@neverblink/linkml 0.11.2 → 0.12.0

package/README.md

@@ -37,7 +37,8 @@ classes:
 // Parse the schema once into a reusable handle. The second argument 
 // is an import map (filename -> YAML source) for any models referenced
 // via LinkML \`imports:\`. Pass {} when there are none.
-const view = LinkML.loadFromString(schema, {});
+const { view, report } = LinkML.loadFromString(schema, {});
+if (!view) throw new Error(JSON.stringify(report, null, 2)); // fatal problems: nothing to generate from
 
 // Then run any generator against the loaded schema.
 const jsonSchema = LinkML.jsonSchema(view);
@@ -60,7 +61,7 @@ There are two ways to load a schema into a `SchemaView` handle:
 
 ```js no-test
 // loadFromPath: the root lives in the import map under its own path.
-const view = LinkML.loadFromPath("model.yaml", {
+const { view } = LinkML.loadFromPath("model.yaml", {
   "model.yaml": schema,
   "person.yaml": personSchema, // referenced via `imports: - person`
 });
@@ -70,17 +71,18 @@ const view = LinkML.loadFromPath("model.yaml", {
 
 Load a schema into a `SchemaView` handle (see above), then pass that handle to any generator:
 
-| Function | Returns | Notes |
-| --- | --- | --- |
-| `loadFromString(schema, importMap)` | `SchemaView` | parse from YAML text; reuse the handle |
-| `loadFromPath(path, importMap)` | `SchemaView` | 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 |
-| `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) |
-| `lint(view, maxProblems?, verbose?)` | `string` | problem summary, empty if valid |
+| Function                                                             | Returns | Notes                                                        |
+|----------------------------------------------------------------------| --- |--------------------------------------------------------------|
+| `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                                            |
+| `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)                             |
+| `graphQl(view, pruningMode?, treeRoot?)`                             | `string` | GraphQL                                                      |
+| `lint(view, inferMessages?)`                                         | `object` | `SchemaValidationReport` (JSON)                              |
 
 See [`index.d.ts`](./index.d.ts) for full type signatures.
 

package/index.d.ts

@@ -11,22 +11,33 @@ export interface SchemaView {
   readonly __linkmlSchemaView: unique symbol;
 }
 
+/**
+ * What loading a schema produced. There is always a report - loading is validating - and a
+ * `view` unless the schema had fatal problems.
+ */
+export interface LoadResult {
+  readonly view?: SchemaView;
+  readonly report: any;
+}
+
 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.
    * @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)
-   * @returns An opaque [[SchemaView]] handle to pass to the generator functions.
+   * @param inferMessages Whether to fill in each issue's human-readable `message` and `details`.
+   * @returns The validation report, and a handle to pass to the generator functions unless the schema had fatal problems.
    */
-  loadFromString(mainSchema: string, importMap: Record<string, string>): SchemaView;
+  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"`).
    * @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]].
-   * @returns An opaque [[SchemaView]] handle to pass to the generator functions.
+   * @param inferMessages Whether to fill in each issue's human-readable `message` and `details`.
+   * @returns The validation report, and a handle to pass to the generator functions unless the schema had fatal problems.
    */
-  loadFromPath(path: string, importMap: Record<string, string>): SchemaView;
+  loadFromPath(path: string, importMap: Record<string, string>, inferMessages?: boolean): LoadResult;
 
   /**
    * Generate JSON Schema from a loaded LinkML schema.
@@ -65,7 +76,7 @@ export interface LinkMLApi {
   /**
    * Materialize a derived LinkML schema from a loaded LinkML schema. Derives classes and prunes unreachable elements.
    * @param schema A [[SchemaView]] handle created with [[loadFromString]] or [[loadFromPath]].
-   * @param pruningMode Pruning mode to use for removing unused elements (classes, types, enums). One of treeRoot|schemaRoot|skip. treeRoot - remove all elements unreachable from the tree_root class. schema - remove all elements unreachable from any of the classes defined in the root schema. skip - do not remove unused elements. Default: treeRoot
+   * @param pruningMode Pruning mode to use for removing unused elements (classes, types, enums). One of treeRoot|schema|skip. treeRoot - remove all elements unreachable from the tree_root class. schema - remove all elements unreachable from any of the classes defined in the root schema. skip - do not remove unused elements. Default: treeRoot
    * @param skipDerivation If true, will not derive classes and instead copy them as-is.
    * @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 outFormat Output serialization format to use. One of yaml|json. Default: yaml
@@ -82,13 +93,21 @@ export interface LinkMLApi {
   tableSchema(schema: SchemaView, treeRoot?: string): string;
 
   /**
-   * Lint a loaded LinkML schema, finding problems that may cause issues when using the model.
+   * Generate a GraphQL Schema from a loaded LinkML schema. Only types/interfaces/scalar/enums, queries must be provided for a specific implementation.
+   * @param schema A [[SchemaView]] handle created with [[loadFromString]] or [[loadFromPath]].
+   * @param pruningMode Pruning mode to use for removing unused elements (classes, types, enums). One of treeRoot|schema|skip. treeRoot - remove all elements unreachable from the tree_root class. schema - remove all elements unreachable from any of the classes defined in the root schema. skip - do not remove unused elements. Default: treeRoot
+   * @param treeRoot Tree root class name to use instead of the schema defined tree_root.
+   * @returns Table Schema, serialized as a JSON
+   */
+  graphQl(schema: SchemaView, pruningMode?: string, treeRoot?: string): string;
+
+  /**
+   * Lint a loaded LinkML schema, finding problems that may cause issues when using the model. This method returns a structured JSON that follows the validation-report.yaml model.  TODO: consider typing the return value in TypeScript using a TypeScript generator. See: https://github.com/NeverBlink-OSS/linkml-scala/issues/127
    * @param schema A [[SchemaView]] handle created with [[loadFromString]] or [[loadFromPath]].
-   * @param maxProblems Maximum number of problems to include in the summary
-   * @param verbose Whether to use the more verbose problem descriptions
-   * @returns The summary of detected problems, or an empty string if everything is correct
+   * @param inferMessages Whether to fill in each issue's human-readable `message` and `details` from the model's `equals_expression`s. Turn it off to get only the structured fields.
+   * @returns A `SchemaValidationReport` as a plain JS object. `issues` is empty if the schema is clean.
    */
-  lint(schema: SchemaView, maxProblems?: number, verbose?: boolean): string;
+  lint(schema: SchemaView, inferMessages?: boolean): any;
 }
 
 export declare const LinkML: LinkMLApi;