[Question/Suggestion] Namespacing/project seperation & interdependencies

[larslarsson]

This is a question if there is any good way to solve seperate projects/namespacing while still being able to reference one project schema from the other without using a domain
"$id": "https://mydomain.com/schema/MyNamepsace/TheSchema.json"
or using fixes filepathing between them. E.g. some form of relative namespacing that when generating can more easily be overriden to the root of the other project. Tools could then configure this for how to resolve that namespace.

Basically if you make a project that you share with multiple other organization & then make an adaptation for another that reference data in the first today I need domain or we need same relative filepaths or accept they are mixed. This is from development perspective to create easy mapping & reuse of custom schemas where each project schemas are not self containing.

How to set it up I have not really any great idea, more example of intention:

"namespaces": {
"A": "MyNamespace"
}

"$ref": "@A/TheSchema.json#MyObject"

or just

"$ref": "@MyNamespace/TheSchema#MyObject"

@A can be found in file root: C:\MyProject\MyNamespace\

[handrews]

@larslarsson can you give an example of what is not working for you today? As in show some schemas and references involving full URIs with domains and explain what part is a problem?

[larslarsson]

Not a bug report, looking for a third option. Reference schemas between "projects" without using domains to download or exact relative file paths. E.g. some way for the use of schema to supply/help find the references & as in coding to assist in this I see the usage of namespace e.g. finding the references in namespace "MyNamespace" can be found in C:\MyNamespace.

The use case is having a big shared schema with multiple users/developers/companies & having another set that refernce it & then as a developer I would prefer to have it in a seperate project where relative pathing might not be the same on my side as on the other users/developers/companies & also without having to go thru a domain. And then during generation I could supply it with info.

One way to implement it to have variables that needs to be specified during generation of code. The other issue is that I might not want to generate the code for the side project & it might be generated in different namespaces. What I see thou is that this is deemed outside the schope of json-schema as I want to bring it more tightly connected to code & development practices.

[handrews]

I understand the general concept, and I realize you're not reporting a bug, but "using domains" is a very vague thing. URIs use domains, we use URIs, but there are various ways to load schemas so that the URIs can be resolved.

The exact mechanisms for loading schemas are implementation-dependent, but the requirements for resolving the URIs once loaded are part of the specification.

I need to understand exactly what isn't working for you, and at exactly what point in the process, in order to tell whether what you're asking for is even within the spec, whether it is already addressed somehow or not, or what.

Please give a very concrete and specific example of the problem and we'll be happy to help you sort it out and see if there is something in the specification we can update.

[larslarsson]

To me using uri might be great for a standardization organization or stuff like OpenApi/swagger but feels cumbersome for company integrations. I presume URI would work conceptually. Relative filepaths works great for internal use & when everything is bundled togheter as blob, but when integration I would have prefered that how we internally organize the schemas/projects would not be reflected in the schema e.g. I want it split & want relative paths in my source control to match & they might not want it split or want slightly different paths. Using fake uri:s

I am currently using relative filepaths where everything is within a project/blob but was thinking having extensions, repackaging & adaptations seperatly just to make structure & logical seperation. If shared with another company we need to have some relative filepaths or make e.g. script to go over it and modify it to match my structure. Basicly I am supplied some schemas that could have dependencies to schemas I own/manage & I don't like their file structure...

I don't really expect it to exist but could be wrong, but maybe I can plan a seed for future specification for how one can organize & bundle schemas. And if it would be added maybe I would in future move out schemas that are shared/common for basic object/concepts. I am missing same concept in the xsd world.

[handrews]

There are lots of ways to use relative URIs with paths without having to specify domain names, but I can't figure out what you want here. I don't know what you mean by "bundled together as a blob." I can't tell what sort of correspondence between your organization and what's in the schema is bothering you, or what would be better. "Packaging" is not within the scope of the spec (beyond things like being able to use $id to put multiple resources in one file, which could be considered "packaging" I suppose).

You can assign any kind of URI to your schemas. urn:uuid: and tag: are two that don't use file paths (although tag: uses domains for namespacing). You can do a lot with URIs, so it's unclear to me why that's not sufficient.

I'm going to have to close this unless you can be clear with an example or a process or something more concrete than a few paragraphs of hand-waving.

[handrews]

By example I mean some actual schemas and URIs and $ids and $refs and maybe a file tree layout if that is relevant.

[larslarsson]

The issue is hand-waving hoping to learn something I overlooked or planting a seed for future versions.
Is urn supported by tools & generators? Is there any samples using urn, or more of cleaver technical solution that requires a bit of tweeking to use?
https://json-schema.org/understanding-json-schema/structuring.html

Example would be great or any other documentation about structuring, hopefully easier than the rfc.
Feel free to close.

[karenetheridge]

@larslarsson I think everything you need is in https://tools.ietf.org/html/draft-handrews-json-schema-02#section-8.2 and https://tools.ietf.org/html/rfc3986. You can use relative names for your individual modular pieces, and swap out base URIs in the parent schema that the references are inserted into -- that's what I do.

[Relequestual]

@larslarsson If you'd like to see more documentation on file / schema organisational strategy, that's an issue to be filed on the respective repo. I can't promise anyone will get to it fast, but at least it's tracked then. We're pretty aware the docs are lacking... it's something we hope to change this year, and hope others will be helping out with that.

I generally find the best and easiest way to do this is to use fully qualified URIs for schemas.

The most popular implementations automatically index added schemas $id values, so they can be referenced.

The nature of URIs means you can use relative URIs for your references as long as your base URI is the same.

[Relequestual]

I'm going to close this for now in expectation that you'll open an issue elsewhere.
Feel free to join and chat more on our slack if you want to chat about such things.

[handrews]

@larslarsson we are working on improving the description of how schemas are loaded and references are resolved (#849), which may help a bit. But otherwise, as @Relequestual notes, an issue on the "understanding json schema" repo would be best to track a documentation request.

We don't really address the support levels of implementations here. If you think a test case is lacking, there is the test suite repo where you can file an issue (I am fairly certain that there is at least one urn: example in the test suite, because that came up before).