Clarify support for external $ref in nextflow_schema.json

[vinay-ebi]

When using nf-schema, $ref values that point to external local JSON files do not appear to be resolved, even when the files exist and are valid JSON Schema.

This makes it difficult to reuse shared schema definitions across pipelines and differs from standard JSON Schema (draft 2020-12) behavior.

I’d like to clarify whether this is an intentional limitation or something that could be supported or documented more explicitly.

Example

  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "allOf": [
    {
      "$ref": "./schemas/genome_info.json#/$defs/genome_info_parameters"
    }
  ]
}```


With:

```pipeline/
├── nextflow_schema.json
└── schemas/
    └── genome_info.json


Validation fails with:

Resolution of $ref [...] failed

The same schema validates correctly with standard JSON Schema validators .

Is resolving external local $ref intentionally unsupported in nf-schema?

If so, would it be possible to document this limitation clearly and suggest recommended patterns for schema reuse (e.g. schema generation or inlining)?

If not, would supporting local filesystem $ref resolution be within scope?

[nvnieuwk]

Hi, draft 2020-12 should be fully supported. I think the issue here is that you misunderstood how the $ref keyword works. This is used to reference a subschema present in the current schema (to avoid duplicate schemas). You can find the documentation here: https://json-schema.org/draft/2020-12/draft-bhutton-json-schema-00#rfc.section.8.2.3.1

I'm sure it is possible to inject another schema inside of a JSON schema but I haven't tried it yet myself.

If you want to use it to validate a file given to a parameter, you can use the custom schema keyword in nf-schema: https://nextflow-io.github.io/nf-schema/2.7.0/nextflow_schema/nextflow_schema_specification/#schema

[nvnieuwk]

BTW, we use this library for our JSON schema validation: https://github.com/harrel56/json-schema/tree/1.5.0 so everything that library supports should be supported in nf-schema

[awgymer]

External ref should be supported for validation but for anything else (samplesheetToList, parameter type casting, etc) in the plugin it could quite likely be borked.

There was once an issue about this on the parent jsonschema repo here but it should have been resolved.

I think perhaps though there is a misunderstanding of how ref actually works and what it represents.
Although you say that other jsonschema tools work to validate with this schema I have some doubts about that given the information in the following links about relative file references in jsonschema:

• Reference to local files (with relative/no path) doesn't work python-jsonschema/jsonschema#98
• https://json-schema.org/understanding-json-schema/structuring#dollarref
• https://stackoverflow.com/questions/67198939/resolve-ref-by-relative-file-path

[vinay-ebi]

We tried using Python jsonschema with the same main and external schemas. Using a registry:

registry = Registry().with_resource(
    external_schema["$id"], Resource.from_contents(external_schema)
)

the $ref to the external schema (genome_info_schema.json#/$defs/genome_info_parameters) resolves correctly. Defaults and $defs are applied as expected.

However, nf-schema fails with:

  "properties": {
    "genome_info": {
      "$ref": "genome_info_schema.json#/$defs/genome_info_parameters"
    }
}

Resolution of $ref [genome_info_schema.json#/$defs/genome_info_parameters] failed

[nvnieuwk]

Hi could you provide a reproducible example?

[awgymer]

I've only had a brief look at the Python library docs but the line you have shown appears to me to be you manually registering the external schema by its id - something we cannot do in nf-schema given we do not know the path to any of your external schema, and something the links in my comment above explain is not an expected part of any jsonschema handling code by default.

In short, it works because you have manually configured the registry.

relevant python lib docs

[vinay-ebi]

Yes, we resolved both schema paths explicitly

import argparse
from pathlib import Path
from jsonschema import Draft202012Validator, validators
from referencing import Registry, Resource

def extend_with_default(validator_class):
    """
    Extend Draft202012Validator to fill default values in instance.
    """
    validate_properties = validator_class.VALIDATORS["properties"]

    def set_defaults(validator, properties, instance, schema):
        for prop, subschema in properties.items():
            if "default" in subschema:
                instance.setdefault(prop, subschema["default"])
        for error in validate_properties(validator, properties, instance, schema):
            yield error

    return validators.extend(
        validator_class, {"properties": set_defaults}
    )

def print_params_help(schema, prefix=""):
    """
    Recursively prints schema parameter names, descriptions, and defaults.
    Works for nested objects and arrays.
    """
    if isinstance(schema, dict):
        # Handle object properties
        if "properties" in schema:
            for name, subschema in schema["properties"].items():
                full_name = f"{prefix}.{name}" if prefix else name
                desc = subschema.get("description", "")
                default = subschema.get("default", None)
                print(f"{full_name}: {desc} (default: {default})")
                # Recurse into nested objects or arrays
                print_params_help(subschema, full_name)

        # Handle arrays
        if schema.get("type") == "array" and "items" in schema:
            items = schema["items"]
            full_name = f"{prefix}[]"
            print_params_help(items, full_name)

        # Handle $ref (just print the reference for help)
        if "$ref" in schema:
            print(f"{prefix}: (referenced schema: {schema['$ref']})")

    elif isinstance(schema, list):
        # Schema as a list of schemas
        for idx, subschema in enumerate(schema):
            full_name = f"{prefix}[{idx}]"
            print_params_help(subschema, full_name)

def print_params_values(obj, prefix=""):
    """
    Recursively prints actual values from the instance after validation.
    """
    if isinstance(obj, dict):
        for k, v in obj.items():
            new_prefix = f"{prefix}.{k}" if prefix else k
            print_params_values(v, new_prefix)
    elif isinstance(obj, list):
        for idx, item in enumerate(obj):
            new_prefix = f"{prefix}[{idx}]"
            print_params_values(item, new_prefix)
    else:
        print(f"{prefix} = {obj}")

def main():
    parser = argparse.ArgumentParser(
        description="Validate JSON parameters against schema with defaults, similar to nf-schema."
    )
    parser.add_argument("--main-schema", required=True, help="Main JSON schema")
    parser.add_argument("--external-schema", required=True, help="External schema referenced by main schema")
    parser.add_argument("--params", required=True, help="JSON parameters to validate")
    parser.add_argument("--help-params", action="store_true", help="Print all parameters with description and defaults")

    args = parser.parse_args()

    main_schema_path = Path(args.main_schema).resolve()
    external_schema_path = Path(args.external_schema).resolve()
    params_path = Path(args.params).resolve()

    for path, desc in [(main_schema_path, "Main schema"),
                       (external_schema_path, "External schema"),
                       (params_path, "Params")]:
        if not path.exists():
            print(f"{desc} not found: {path}")
            parser.print_help()
            return

    # Load schemas and params
    main_schema = json.loads(main_schema_path.read_text())
    external_schema = json.loads(external_schema_path.read_text())
    params = json.loads(params_path.read_text())

    # Register external schema
    registry = Registry().with_resource(
        external_schema["$id"], Resource.from_contents(external_schema)
    )

    # Validator with defaults applied
    DefaultValidator = extend_with_default(Draft202012Validator)
    validator = DefaultValidator(main_schema, registry=registry)

    # Print help if requested
    if args.help_params:
        print("\nAvailable parameters (name: description [default]):\n")
        print_params_help(main_schema)
        return

    # Validate and apply defaults
    errors = sorted(validator.iter_errors(params), key=lambda e: e.path)
    if errors:
        print("\nValidation failed ❌\n")
        for e in errors:
            location = ".".join(str(p) for p in e.path)
            print(f"At '{location}': {e.message}")
        return

    print("Validation successful ✅\n")
    print("Parameters with values (defaults applied):\n")
    # print_params_values(params)

if __name__ == "__main__":
    main()

We are trying achive similar to this in nf-schema . We are including a subworkflow into a workflow, and we do not want to duplicate the common parameters and their validations.

[awgymer]

So yes, you are manually registering schema.

It seems that we do in fact not support external ref in the way I thought but nonetheless I'm a bit unsure on what the solution here should be.

There are a few things to consider:

• the spec explicitly defines that URI are not necessarily a network locator, only an identifier.

• the spec defines that the top-level $id of a schema MUST resolve to absolute URI

• the spec defines that this base URI (from $id) will be used as the base for relative URI references within the schema

• the jsonschema library does not make any attempts to actually fetch schema that are not already loaded or passed directly to the validator

• we cannot know about the content of a schema without parsing it

• in order to pre-register schema we would need to know all the possible schema and their desired URI

• in order to dynamically fetch and register schema based on relative file paths the top-level schema URI would need to somehow be modified to not be $id if it was set to something other than the current absolute path of the file it is found in

Overall my reading suggests that this kind of split schema is not hugely recommended and support for it is fairly lacking in core libraries beyond requiring manual registration of all the schema to their correct URI, but as addressed above that is not a particularly simple feat

[nvnieuwk]

It might be nice as a future feature, but I'd say this is fairly low priority right now. In the (near?) future the parameter validation will fully happen in the Nextflow codebase so it will get removed from here eventually. I'm a bit hesitant to implement such features if they will get redundant soon anyways