Suggestion: make requirements regarding URIs more explicit

[gburning]

Had a problem that is fully a user error on my part but could have been alleviated with more explicit types and/or JSDoc/TSDoc comments.

The tool I'm building (a Node.js application) programmatically reads *.schema.json files from a specific directory. In my naiveté I was then using the resolved, absolute, paths directly with getSchema from the experimental API.

This worked fine on my Mac but became a problem on a system using drive letters (Windows in this case). The library (correctly) parsed D:\path\to\file.json as it having an invalid D: scheme.

Long story short, I realized after digging through the code that I needed to use either relative paths or convert them to valid URIs (using file://). Also, I just now noticed that this is indeed documented in the README.

This leads to my questions/suggestions:

1. From my understanding it is preferable to use relative paths rather than absolute URIs (file://...)? Is this correct and if so, why? In my case the URIs are only used to resolve the path the schema files.
2. Would it be possible to implement stronger types and/or JSDoc/TSDoc comments for the various exports? Particularly where URIs are expected. Perhaps even allowing URL objects using the built in type?

• It would be a nice DX improvement in general to have at least some of the descriptions from the README as comment blocks. Jumping back and forth to the README gets fairly tedious and I had missed the part about URIs under "validation" since I'm not using the library for that.

---

Again, I realize this comes down to me missing these things in the documentation, but I believe it could be made more accessible with some tweaks. I'm also ready to help and pitch in if wanted, as long as I know what you would want.