Feature Request: Add Support for $id-Based Schema Resolution

[djedi]

Is your enhancement related to a problem? Please describe.

The YAML extension currently resolves $ref paths relative to the base URL of the parent schema, without considering the $id field as a unique identifier. This creates issues when:

• Relative $ref paths don't align with the actual hosting or file structure of the schema files.
• The schema references are expected to be resolved using their $id, as supported by tools like AJV.

For example:

    $schema: "https://example.com/survey/types/root.schema.json"
    type: object
    properties:
      config:
        $ref: "/survey/types/modelconfig.schema.json"

The schema at /survey/types/modelconfig.schema.json includes:

    {
      "$id": "/survey/types/modelconfig.schema.json",
      "type": "object",
      "properties": {
        "example": { "type": "string" }
      }
    }

VSCode tries to resolve /survey/types/modelconfig.schema.json relative to the base URL but fails if the file is not accessible at that exact path, even though the schema has a valid $id. This leads to schema resolution errors and breaks workflows involving interdependent schemas.

---

Describe the solution you would like

The YAML extension should support $id-based schema resolution in addition to the current relative path resolution. Specifically:

1. When encountering a $ref, the extension should:
   • First, attempt to resolve it relative to the base URL (current behavior).
   • If resolution fails, look for a schema in a registry that matches the $id specified in the referenced schema.
2. Implement a schema registry to preload or dynamically cache schemas by $id for efficient resolution.

This approach aligns with the JSON Schema specification and ensures compatibility with tools like AJV.

---

Describe alternatives you have considered

1. Manual Schema Mapping: Use the yaml.schemas setting to manually map schemas to files or URLs. This works but is error-prone and scales poorly for large or dynamic schema setups. Example:

   "yaml.schemas": {
     "./schemas/modelconfig.schema.json": "*.yaml"
   }
   

2. Inline Definitions: Refactor schemas to use $defs and reference them with # paths. This resolves the issue in VSCode but breaks compatibility with tools like AJV, which are essential for CI/CD workflows.

3. Flatten Schemas: Merge schemas into a single file to avoid external references. This is infeasible for large projects with shared schema components.

---

Additional context

This enhancement would improve compatibility with the JSON Schema specification, where $id is treated as a unique identifier for schemas. It would also make the YAML extension more robust for advanced workflows.

References

• JSON Schema Specification – $id
• AJV Documentation – Adding Schemas by $id

Example Use Case

In our setup, schemas are referenced by $ref paths but rely on $id for resolution. While tools like AJV handle this setup correctly, the VSCode YAML extension fails to resolve these references, making it challenging to use in development workflows.

Environment:

• VSCode Version: 1.96.2
• YAML Extension Version: 1.15.0
• JSON Schema Draft: 07
• Operating System: MacOS