mattyod / matic Goto Github PK
View Code? Open in Web Editor NEWAutomated HTML documentation for JSON schemas
License: MIT License
Automated HTML documentation for JSON schemas
License: MIT License
Current $ref implementation diverges from the v4 spec.
see:
http://json-schema.org/latest/json-schema-core.html#anchor25
http://tools.ietf.org/html/draft-pbryan-zyp-json-ref-03#section-3
http://tools.ietf.org/html/draft-ietf-appsawg-json-pointer-07
In contrast, the only way in matic to include a subschema from another file seems to be to have a file in a directory relative to the main schema, with one subschema per file.
1 A schema built to work with matic references does not validate according to v4 rules.
2 Lack of JSON Pointer support makes it impossible to refer to parts of a subschema
I get the following error message when I use an enum:
/usr/local/lib/node_modules/matic/lib/mergeSchemas.js:10
if(key.match(/$ref/)) {
^
TypeError: Object 0 has no method 'match'
at /usr/local/lib/node_modules/matic/lib/mergeSchemas.js:10:14
at Array.forEach (native)
at Function..each..forEach (/usr/local/lib/node_modules/matic/node_modules/underscore/underscore.js:78:11)
at itterate (/usr/local/lib/node_modules/matic/lib/mergeSchemas.js:8:7)
at /usr/local/lib/node_modules/matic/lib/mergeSchemas.js:35:9
at Function..each..forEach (/usr/local/lib/node_modules/matic/node_modules/underscore/underscore.js:86:24)
at itterate (/usr/local/lib/node_modules/matic/lib/mergeSchemas.js:8:7)
at /usr/local/lib/node_modules/matic/lib/mergeSchemas.js:35:9
at Function..each..forEach (/usr/local/lib/node_modules/matic/node_modules/underscore/underscore.js:86:24)
at itterate (/usr/local/lib/node_modules/matic/lib/mergeSchemas.js:8:7)
Here's the enum:
"phoneNumber": {
"type": "object",
"id": "phoneNumber",
"required": true,
"properties": {
"channel": {
"type": "string",
"id": "channel",
"required": true,
"enum": [
"cell",
"work",
"home"
]
},
"number": {
"type": "string",
"id": "number",
"required": true
}
}
}
Hi again,
I have a structure similar to this:
{ "type":"object", "name": "name", "description": "description", "id": "id", "required":false, "properties":{ "PROP LVL 1": { "type":"array", "title": "title", "description": "description", "minitems": "0", "maxitems": "2", "required":false, "items": { "type":"object", "name": "name", "description": "description", "required":false, "properties":{ "PROP LVL 1.1": { "type":"number", "title": "title", "name": "name", "description": "description", "minimum": "0", "maximum": "2", "id": "id", "required":true }, "PROP LVL 1.2": { "type":"number", "title": "title", "name": "name", "description": "description", "id": "id", "required":false } } } }
Do you know why the PROP LVL 1.1 is not showing in the template?
I am using the simple example code.
Thanks,
Carlos
The current examples break due to use of anonymous block. Running matic for matic-very-simple-example shows the following error:
Warning: missing space before text for line 27 of jade file.
/usr/lib/node_modules/jade/lib/runtime.js:202
throw err;
^
Error: ./templates/:35
33| | using
34| a(href='https://www.github.com/mattyod/matic-very-simple-example/') a simple example
35| block
36| script(src='js/jquery.js')
37| script(src='js/schema.js')
Anonymous blocks are not allowed unless they are part of a mixin.
at Parser.parseMixinBlock (/usr/lib/node_modules/jade/lib/parser.js:494:13)
at Parser.parseExpr (/usr/lib/node_modules/jade/lib/parser.js:205:21)
at Parser.block (/usr/lib/node_modules/jade/lib/parser.js:660:25)
at Parser.tag (/usr/lib/node_modules/jade/lib/parser.js:777:26)
at Parser.parseTag (/usr/lib/node_modules/jade/lib/parser.js:690:17)
at Parser.parseExpr (/usr/lib/node_modules/jade/lib/parser.js:199:21)
at Parser.block (/usr/lib/node_modules/jade/lib/parser.js:660:25)
at Parser.tag (/usr/lib/node_modules/jade/lib/parser.js:777:26)
at Parser.parseTag (/usr/lib/node_modules/jade/lib/parser.js:690:17)
at Parser.parseExpr (/usr/lib/node_modules/jade/lib/parser.js:199:21)
When running matic for a JSON file with recursive references ($ref), then a RangeError is caused.
C:\node_modules\matic\lib\merge.js:52
itterate(val, key, obj, schema);
^
RangeError: Maximum call stack size exceeded
at C:\node_modules\matic\lib\merge.js:52:9
at Function._.each._.forEach (C:\node_modules\matic\node_modules\underscore\underscore.js:87:22)
at C:\node_modules\matic\lib\merge.js:14:7
at C:\node_modules\matic\lib\merge.js:52:9
at Function._.each._.forEach (C:\node_modules\matic\node_modules\underscore\underscore.js:87:22)
at C:\node_modules\matic\lib\merge.js:14:7
at merge (C:\node_modules\matic\lib\merge.js:64:12)
at C:\node_modules\matic\lib\merge.js:33:36
at Function._.each._.forEach (C:\node_modules\matic\node_modules\underscore\underscore.js:87:22)
at C:\node_modules\matic\lib\merge.js:14:7
As example I cloned matic-draft4-example([https://github.com/mattyod/matic-draft4-example). And I changed the example.json file to the following:
{
"title": "Matic Draft 4 Example",
"Description": "An example schema to demonstrate Matic",
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"items": {
"allOf": [
{
"$ref": "#definitions/foo"
},
{
"$ref": "#definitions/bar"
}
],
"anyOf": [
{
"$ref": "#definitions/foo"
}
],
"oneOf": [
{
"$ref": "#definitions/bar"
}
]
},
"definitions": {
"foo": {
"title": "Foo",
"description": "A foo schema",
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"url": {
"title": "A url",
"description": "An example url schema",
"type": "string",
"format": "uri",
"example": "http://github.com/mattyod/matic"
},
"list": {
"title": "A list",
"description": "A list of things",
"type": "array",
"example": [
"one",
"two",
"three"
]
},
"recursion" : {
"$ref": "#definitions/foo"
}
},
"required": [
"url"
]
},
"bar": {
"title": "Bar",
"description": "A bar schema",
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"thing": {
"title": "thing",
"description": "a thing that uses a local pointer to an other thing for it's properties",
"type": "object",
"properties": {
"$ref": "example"
}
},
"thing2": {
"$ref": "#/properties/otherThing"
},
"otherThing": {
"id": "example",
"type": "integer"
}
},
"required": [
"thing",
"thing2",
"otherThing"
]
}
}
}
Note that I've inlined the bar and foo objects. And to foo I have added the following property:
"recursion" : {
"$ref": "#definitions/foo"
}
So it contains a recursive reference which is allowed by the JSON Schema spec.
When I run (on Windows):
npm run unit
The following test does fail:
lib/index
1) returns an object which indexes all the files from the clipboard
I attached the full command output
Update: it seems that it is an issue with Windows vs unix path separators. The unit test does expect
schemas/bar.json
but it receives schemas\\bar.json
Add a quick readme and instructions to start app.
....
"payout_methods": {
"type": "object",
"oneOf": [
{ "$ref": "#/definitions/bitcoin.json" },
{ "$ref": "#/definitions/sepa.json" },
{ "$ref": "#/definitions/uk_bank.json" }
]
}
....
Error message:
/usr/local/lib/node_modules/jade/lib/runtime.js:231
throw err;
^
TypeError: templates/mixins/itterate.jade:22
20| mixin itterate(item, item.title, obj)
21| else
22| - var schema = key.match(/^(properties)|(patternProperties)|(items)$/) ? obj : val
23| mixin itterate(item, name, schema)
24| else
25| dt
Cannot call method 'match' of undefined
at Object.eval (eval at (/usr/local/lib/node_modules/jade/lib/index.js:216:8), :292:18)
at Object.jade_mixins.itterate (eval at (/usr/local/lib/node_modules/jade/lib/index.js:216:8), :304:4)
at Object.eval (eval at (/usr/local/lib/node_modules/jade/lib/index.js:216:8), :254:24)
at Object.jade_mixins.itterate (eval at (/usr/local/lib/node_modules/jade/lib/index.js:216:8), :304:4)
at Object.eval (eval at (/usr/local/lib/node_modules/jade/lib/index.js:216:8), :295:24)
at Object.jade_mixins.itterate (eval at (/usr/local/lib/node_modules/jade/lib/index.js:216:8), :304:4)
at Object.eval (eval at (/usr/local/lib/node_modules/jade/lib/index.js:216:8), :295:24)
at Object.jade_mixins.itterate (eval at (/usr/local/lib/node_modules/jade/lib/index.js:216:8), :304:4)
at jade_debug.unshift.lineno (eval at (/usr/local/lib/node_modules/jade/lib/index.js:216:8), :486:24)
at eval (eval at (/usr/local/lib/node_modules/jade/lib/index.js:216:8), :495:4)
I'm trying to store matic output to Subversion.
However "assets" in .maticrc includes all files and directories, including .svn, which causes problems when committing.
Any schemas path other than "schemas" will still create the target output folder specified, but will NOT render the respective .html output files there.
I was able to track the problem down to the " rightclick / copy" - script.
Lines 49 to 51 look as follows:
if (fileSuffix.test(suffix)) {
clip[docPath] = fs.readFileSync(fullPath, enc);
}
Before the synchronous file reading operation the object "this.clipboard.files.schemas" contains one schema-path less than after. So somehow this "this.clipboard.files.schemas"-object is getting a local docPath of one of the .json schemas in the "schemas"-folder added at this point, but only if your schemas path is "schemas".
Not so if it is any other custom-path.
Why?
Btw., my jade module is installed globally - if that makes any difference.
Handle sub schema $ref paths properly.
Currently the path within a $ref is joined to the main or parent schema's path not the parent + child + further child's path.
i.e. I have main.json, and thing.json. thing.json as a { "$ref": "anotherthing.json" }
in folder structure such as
main
|
- things
|
- thing.json
- anotherThing.json
Link generated in mergeSchemas.js will be main/anotherThing.json not main/things/anotherThing.json
@Matic a new topic on json-schema/json-schema#90 may be of interest to you, we could certainly benefit from your expert knowledge and experience in this area.
Please drop us a line...
Handle "typeof null" properly.
This is a great app. Just one concern: it doesn't currently handle relative references -- references to sub-schemas within the same document. See examples below.
I took a stab at extending (forking?) your merge code to handle relative references; however, it currently assumes that relative references start with a '#'. I'm not sure that is always true.
{ "id": "root",
"properties": {
"a": { "id": "a"},
"b": { "extends": { "$ref": "#a" }},
"c": { "extends": { "$ref": "#root/properties/b" }}
}
}
Like title says, I could not find any link to live examples of how the generated documentation will look like, except for http://mattyod.github.io/matic-draft4-example/example.html, which seems only a showcasing of a partial functionality.
hello
npm install -g matic
matic
module.js:340
throw err;
^
Error: Cannot find module 'jade'
i suggest :
"dependencies": {
"underscore": "1.x",
"jade": "0.27.x"
},
Cordialy
Ami
When I run matic on my schema I get an error:
fs.js:462
var r = binding.read(fd, buffer, offset, length, position);
^
Error: EISDIR, illegal operation on a directory
at Object.fs.readSync (fs.js:462:19)
at Object.fs.readFileSync (fs.js:296:28)
at rethrow (/usr/local/lib/node_modules/jade/lib/runtime.js:155:27)
at eval (eval at (/usr/local/lib/node_modules/jade/lib/jade.js:176:8), :429:3)
at /usr/local/lib/node_modules/jade/lib/jade.js:181:12
at /usr/local/lib/node_modules/matic/lib/build.js:40:48
at Array.forEach (native)
at module.exports (/usr/local/lib/node_modules/matic/lib/build.js:33:26)
at Object.module.exports.generate (/usr/local/lib/node_modules/matic/lib/matic.js:42:5)
at Object. (/usr/local/lib/node_modules/matic/bin/matic:16:10)
Here is the schema:
{
"type":"object",
"$schema": "http://json-schema.org/draft-03/schema",
"id": "#",
"required":false,
"properties":{
"images": {
"type":"array",
"id": "images",
"required":false,
"items":
{
"type":"object",
"id": "0",
"required":false,
"properties":{
"attitude": {
"type":"string",
"id": "attitude",
"required":false
},
"bucket": {
"type":"string",
"id": "bucket",
"required":false
},
"cameraModelComponentList": {
"type":"string",
"id": "cameraModelComponentList",
"required":false
},
"cameraModelType": {
"type":"string",
"id": "cameraModelType",
"required":false
},
"cameraPosition": {
"type":"string",
"id": "cameraPosition",
"required":false
},
"cameraVector": {
"type":"string",
"id": "cameraVector",
"required":false
},
"contributor": {
"type":"string",
"id": "contributor",
"required":false
},
"dateAdded": {
"type":"string",
"id": "dateAdded",
"required":false
},
"drive": {
"type":"string",
"id": "drive",
"required":false
},
"filterName": {
"type":"string",
"id": "filterName",
"required":false
},
"instrument": {
"type":"string",
"id": "instrument",
"required":false
},
"itemName": {
"type":"string",
"id": "itemName",
"required":false
},
"lmst": {
"type":"string",
"id": "lmst",
"required":false
},
"mastAz": {
"type":"string",
"id": "mastAz",
"required":false
},
"mastEl": {
"type":"string",
"id": "mastEl",
"required":false
},
"sampleType": {
"type":"string",
"id": "sampleType",
"required":false
},
"scaleFactor": {
"type":"string",
"id": "scaleFactor",
"required":false
},
"sclk": {
"type":"string",
"id": "sclk",
"required":false
},
"site": {
"type":"string",
"id": "site",
"required":false
},
"sol": {
"type":"string",
"id": "sol",
"required":false
},
"subframeRect": {
"type":"string",
"id": "subframeRect",
"required":false
},
"urlList": {
"type":"string",
"id": "urlList",
"required":false
},
"utc": {
"type":"string",
"id": "utc",
"required":false
},
"xyz": {
"type":"string",
"id": "xyz",
"required":false
}
}
}
},
"most_recent": {
"type":"string",
"id": "most_recent",
"required":false
},
"sol": {
"type":"number",
"id": "sol",
"required":false
},
"type": {
"type":"string",
"id": "type",
"required":false
}
}
}
Revisit Matic to support draft 4.
Is it possible and/or indeed valuable to continue supporting draft 3 or do we just move on?
Any plans to support draft 7?
The npm test command does fail on Windows devices because the npm run lint
and npm run jscs
commands are unix style.
Also by default files are checked out with crlf by git on Windows
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google ❤️ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.