Specification of static repository format


#1

Coming here from Github.

The official documentation currently does not say a lot about the requirements on a static repository; only to use Iglu Central as an example. This older topic doesn’t provide much detail beyond that, either.

I’d like clarification on a couple of points:

  • What are other folders besides schemas? Are any names reserved, and for which purpose?
  • Is the Mimetype with which the schemas are served relevant at all? (The example serves binary/octet-stream, which isn’t very useful for opening schemas in/from the browser.)
  • Will HTML files spread out through the folder hierarchy influence schema resolving at all? (Think of README.md files compile to index.html.)
  • Is the structure of the main index.html relevant at all, or can we put whatever we want there?

For context, we are not (yet) using Iglu but would like to keep our repository consistent with it. (Mostly: we have to use regular HTTP URIs in $ref, of course.)


#2

Hey @reitzig,

Thanks again for raising this - Iglu Static Registry supposed to be as simple and minimalistic as possible (“primitive” and “dumb” are also right words) with as few moving parts as possible. That’s why we didn’t bother to clarify these points before (but we will now).

What are other folders besides schemas? Are any names reserved, and for which purpose?

None. schemas/ is the only one required endpoint. We store DDLs and JSON Paths in Iglu Central just for convenience as they describe same entities and should be released together, but this is a subject for change in future and not a requirement at all.

Is the Mimetype with which the schemas are served relevant at all? (The example serves binary/octet-stream, which isn’t very useful for opening schemas in/from the browser.)

No, it is not. As long as Iglu Client can perform an HTTP request - headers do not matter.

Will HTML files spread out through the folder hierarchy influence schema resolving at all? (Think of README.md files compile to index.html.)

No, they shouldn’t affect resolution as Iglu Client cares only about specific endpoints. But they can affect Igluctl work as static generate and lint commands are very opionated about file structure of registry.

Is the structure of the main index.html relevant at all, or can we put whatever we want there?

Nope. index.html is a historical artifact.