New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Need a structured Schema for the JSON #14987

Closed
thesteve0 opened this Issue Oct 2, 2015 · 21 comments

Comments

Projects
None yet
9 participants
@thesteve0

thesteve0 commented Oct 2, 2015

Can we please get a structured JSON Schema so we can validate and understand json documents submitted to Kube

@thesteve0

This comment has been minimized.

Show comment
Hide comment
@thesteve0

thesteve0 Oct 2, 2015

Here is the schema page I am talking about:

http://json-schema.org

and here is an example of what it should look like - please look at the full code example

http://json-schema.org/example2.html

thesteve0 commented Oct 2, 2015

Here is the schema page I am talking about:

http://json-schema.org

and here is an example of what it should look like - please look at the full code example

http://json-schema.org/example2.html

@bgrant0607

This comment has been minimized.

Show comment
Hide comment
@bgrant0607
Member

bgrant0607 commented Oct 3, 2015

Forked from: #14294 (comment)

@bgrant0607

This comment has been minimized.

Show comment
Hide comment
@bgrant0607

bgrant0607 Oct 3, 2015

Member

@thesteve0 Please copy your comments from the PR.

Note that we currently use Swagger 1.2. Help upgrading to Swagger 2.0 #13414 would be appreciated.

What is the gap between Swagger 2.0 and what you're asking for?

Member

bgrant0607 commented Oct 3, 2015

@thesteve0 Please copy your comments from the PR.

Note that we currently use Swagger 1.2. Help upgrading to Swagger 2.0 #13414 would be appreciated.

What is the gap between Swagger 2.0 and what you're asking for?

@thesteve0

This comment has been minimized.

Show comment
Hide comment
@thesteve0

thesteve0 Oct 3, 2015

Copying from the the other PR - I think this is the most relevant

please look at the full example on this page

http://json-schema.org/example2.html
(it's toward the bottom of the page and I had to click the + to expand and see it)

I want something like that - the swagger output does not look like that.

For example look at the "nfs" type - that is so easy for me to go ahead and think about how I make that AND I can also use a bunch of different tooling around that

"nfs": {
            "properties": {
                "type": { "enum": [ "nfs" ] },
                "remotePath": {
                    "type": "string",
                    "pattern": "^(/[^/]+)+$"
                },
                "server": {
                    "type": "string",
                    "oneOf": [
                        { "format": "host-name" },
                        { "format": "ipv4" },
                        { "format": "ipv6" }
                    ]
                }
            },
            "required": [ "type", "server", "remotePath" ],
            "additionalProperties": false
        },

This can then be used in tooling, for example, Altova's XML spy - http://www.altova.com/download-json-schema-editor.html or any of the tooling and libraries on this page

http://json-schema.org/implementations.html

For example we could take the jdorn/json-editor and make a simple HTML form for creating the kube (or openshift) JSON - way friendlier than hacking straight JSON files

https://github.com/jdorn/json-editor

Check out the beautiful auto-generated doc we could also product

https://github.com/lbovet/docson

Again, sorry if I seem to be monopolizing conversation here - I am more than willing to strike this up somewhere else.

thesteve0 commented Oct 3, 2015

Copying from the the other PR - I think this is the most relevant

please look at the full example on this page

http://json-schema.org/example2.html
(it's toward the bottom of the page and I had to click the + to expand and see it)

I want something like that - the swagger output does not look like that.

For example look at the "nfs" type - that is so easy for me to go ahead and think about how I make that AND I can also use a bunch of different tooling around that

"nfs": {
            "properties": {
                "type": { "enum": [ "nfs" ] },
                "remotePath": {
                    "type": "string",
                    "pattern": "^(/[^/]+)+$"
                },
                "server": {
                    "type": "string",
                    "oneOf": [
                        { "format": "host-name" },
                        { "format": "ipv4" },
                        { "format": "ipv6" }
                    ]
                }
            },
            "required": [ "type", "server", "remotePath" ],
            "additionalProperties": false
        },

This can then be used in tooling, for example, Altova's XML spy - http://www.altova.com/download-json-schema-editor.html or any of the tooling and libraries on this page

http://json-schema.org/implementations.html

For example we could take the jdorn/json-editor and make a simple HTML form for creating the kube (or openshift) JSON - way friendlier than hacking straight JSON files

https://github.com/jdorn/json-editor

Check out the beautiful auto-generated doc we could also product

https://github.com/lbovet/docson

Again, sorry if I seem to be monopolizing conversation here - I am more than willing to strike this up somewhere else.

@thesteve0

This comment has been minimized.

Show comment
Hide comment
@thesteve0

thesteve0 Oct 3, 2015

Does swagger have a way to just spit out a schema and not all the API calls as well? Because really, I don't want all the swagger stuff for this - I just want a JSON Schema Doc that has OneOf stuff filled in and more like that.

thesteve0 commented Oct 3, 2015

Does swagger have a way to just spit out a schema and not all the API calls as well? Because really, I don't want all the swagger stuff for this - I just want a JSON Schema Doc that has OneOf stuff filled in and more like that.

@lavalamp

This comment has been minimized.

Show comment
Hide comment
@lavalamp
Member

lavalamp commented Oct 5, 2015

@lavalamp

This comment has been minimized.

Show comment
Hide comment
@lavalamp

lavalamp Oct 5, 2015

Member

Please reopen if this isn't a satisfactory answer.

Member

lavalamp commented Oct 5, 2015

Please reopen if this isn't a satisfactory answer.

@lavalamp lavalamp closed this Oct 5, 2015

@DirectXMan12

This comment has been minimized.

Show comment
Hide comment
@DirectXMan12

DirectXMan12 Oct 6, 2015

Contributor

Does swagger have a way to just spit out a schema and not all the API calls as well? Because really, I don't want all the swagger stuff for this - I just want a JSON Schema Doc that has OneOf stuff filled in and more like that.

Like I mentioned before, it seems, at least, Swagger 2.0's model spec is explicitly a subset of the JSONSchema spec. AFAICT, we don't export more detailed formats like you suggest above, though
(in part due to how our Swagger spec is generated, I suspect).

You should just be able to grab the swagger spec, and then pay attention only to the models field: https://github.com/kubernetes/kubernetes/blob/gh-pages/swagger-spec/api/v1/index.html#L10955

Contributor

DirectXMan12 commented Oct 6, 2015

Does swagger have a way to just spit out a schema and not all the API calls as well? Because really, I don't want all the swagger stuff for this - I just want a JSON Schema Doc that has OneOf stuff filled in and more like that.

Like I mentioned before, it seems, at least, Swagger 2.0's model spec is explicitly a subset of the JSONSchema spec. AFAICT, we don't export more detailed formats like you suggest above, though
(in part due to how our Swagger spec is generated, I suspect).

You should just be able to grab the swagger spec, and then pay attention only to the models field: https://github.com/kubernetes/kubernetes/blob/gh-pages/swagger-spec/api/v1/index.html#L10955

@thesteve0

This comment has been minimized.

Show comment
Hide comment
@thesteve0

thesteve0 Oct 6, 2015

Ok I see how it is following the spec so I guess this can be closed but it doesn't look like we are fully utilizing the power of the spec. For example look at this in ContainerPort.

"protocol": {
      "type": "string",
      "description": "Protocol for port. Must be UDP or TCP. Defaults to \"TCP\"."
     }

Looks like it should be:

"protocol": {
      "type": "string",
      "oneOf": [
                       "UDP","TCP"
                    ]
      "description": "Protocol for port. Must be UDP or TCP. Defaults to \"TCP\"."
     }

We also don't use patterns for strings where they might apply (like in an IP or URL) and we do required fields differently
http://json-schema.org/example2.html

That said @DirectXMan12 (Solly) might be right that this is a limitation of Swagger. I will re-open just to get people to read my minor complaints now but feel free to close again without me yelling ;)

Thanks for the discussion!

thesteve0 commented Oct 6, 2015

Ok I see how it is following the spec so I guess this can be closed but it doesn't look like we are fully utilizing the power of the spec. For example look at this in ContainerPort.

"protocol": {
      "type": "string",
      "description": "Protocol for port. Must be UDP or TCP. Defaults to \"TCP\"."
     }

Looks like it should be:

"protocol": {
      "type": "string",
      "oneOf": [
                       "UDP","TCP"
                    ]
      "description": "Protocol for port. Must be UDP or TCP. Defaults to \"TCP\"."
     }

We also don't use patterns for strings where they might apply (like in an IP or URL) and we do required fields differently
http://json-schema.org/example2.html

That said @DirectXMan12 (Solly) might be right that this is a limitation of Swagger. I will re-open just to get people to read my minor complaints now but feel free to close again without me yelling ;)

Thanks for the discussion!

@DirectXMan12

This comment has been minimized.

Show comment
Hide comment
@DirectXMan12

DirectXMan12 Oct 7, 2015

Contributor

@thesteve0 I think it's more of a limitation of go-restful, which automatically generates our Swagger spec based on the API objects (and gets doc from comments above each field). Just to clarify things, we currently generate a Swagger 1.2 spec, which isn't explicitly JSON Schema. Swagger 2.0 is.

It would be nice (and interesting) to see something like that eventually (if you open a separate issue, tag me in it), but I think right now we don't actually have that information readily available in a way that could be converted into the JSON Schema validators.

It looks like Swagger 2.0 (which we aren't using yet, but IIRC is on the list of things to do) supports most of the validators (not oneOf, which is for matching against multiple schemas, but it does support enum, which would work in your example).

Contributor

DirectXMan12 commented Oct 7, 2015

@thesteve0 I think it's more of a limitation of go-restful, which automatically generates our Swagger spec based on the API objects (and gets doc from comments above each field). Just to clarify things, we currently generate a Swagger 1.2 spec, which isn't explicitly JSON Schema. Swagger 2.0 is.

It would be nice (and interesting) to see something like that eventually (if you open a separate issue, tag me in it), but I think right now we don't actually have that information readily available in a way that could be converted into the JSON Schema validators.

It looks like Swagger 2.0 (which we aren't using yet, but IIRC is on the list of things to do) supports most of the validators (not oneOf, which is for matching against multiple schemas, but it does support enum, which would work in your example).

@thesteve0

This comment has been minimized.

Show comment
Hide comment
@thesteve0

thesteve0 Oct 7, 2015

Thanks Solly! I don't want to be a pain to your group but @smarterclayton @ironcladlou @deads2k @derekwaynecarr you know what is coming your way now ;)

@DirectXMan12 do you want me to open another issue for this?

thesteve0 commented Oct 7, 2015

Thanks Solly! I don't want to be a pain to your group but @smarterclayton @ironcladlou @deads2k @derekwaynecarr you know what is coming your way now ;)

@DirectXMan12 do you want me to open another issue for this?

@intellix

This comment has been minimized.

Show comment
Hide comment
@intellix

intellix Oct 1, 2016

I'm going to start looking into K8S and need to learn what I need to write in my Manifest files to create services, pods etc. JSON Schema coupled with an autocomplete plugin that reads from such a schema would be the easiest way to write manifest files, as you generally have an idea of what information you need to provide for Services, Pods, Replication Controllers etc as you type.

This would be the bees knees for me. @DirectXMan12 said to create another issue. Did anyone do this already?

Googled around, hoping at least someone had already created a Schema so I could get to work, but this is all I could find: https://github.com/jbeda/kubernetes-detached/tree/master/api/doc

intellix commented Oct 1, 2016

I'm going to start looking into K8S and need to learn what I need to write in my Manifest files to create services, pods etc. JSON Schema coupled with an autocomplete plugin that reads from such a schema would be the easiest way to write manifest files, as you generally have an idea of what information you need to provide for Services, Pods, Replication Controllers etc as you type.

This would be the bees knees for me. @DirectXMan12 said to create another issue. Did anyone do this already?

Googled around, hoping at least someone had already created a Schema so I could get to work, but this is all I could find: https://github.com/jbeda/kubernetes-detached/tree/master/api/doc

@smarterclayton

This comment has been minimized.

Show comment
Hide comment
@smarterclayton

smarterclayton Oct 1, 2016

Contributor

The openapi spec docs in Kube 1.4 and 1.5-alpha (master) should be
jsonschema.

https://github.com/kubernetes/kubernetes/tree/master/api/openapi-spec

On Oct 1, 2016, at 12:09 PM, Dominic Watson notifications@github.com
wrote:

I'm going to start looking into K8S and need to learn what I need to write
in my Manifest files to create services, pods etc. JSON Schema coupled with
an autocomplete plugin that reads from such a schema would be the easiest
way to write manifest files, as you generally have an idea of what
information you need to provide for Services, Pods, Replication Controllers
etc as you type.

This would be the bees knees for me. @DirectXMan12
https://github.com/DirectXMan12 said to create another issue. Did anyone
do this already?

Googled around, hoping at least someone had already created a Schema so I
could get to work, but this is all I could find:
https://github.com/jbeda/kubernetes-detached/tree/master/api/doc


You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
#14987 (comment),
or mute the thread
https://github.com/notifications/unsubscribe-auth/ABG_p6s9mYUMCtlxXUaSCLuVzDBVH8i9ks5qvoW4gaJpZM4GIFPd
.

Contributor

smarterclayton commented Oct 1, 2016

The openapi spec docs in Kube 1.4 and 1.5-alpha (master) should be
jsonschema.

https://github.com/kubernetes/kubernetes/tree/master/api/openapi-spec

On Oct 1, 2016, at 12:09 PM, Dominic Watson notifications@github.com
wrote:

I'm going to start looking into K8S and need to learn what I need to write
in my Manifest files to create services, pods etc. JSON Schema coupled with
an autocomplete plugin that reads from such a schema would be the easiest
way to write manifest files, as you generally have an idea of what
information you need to provide for Services, Pods, Replication Controllers
etc as you type.

This would be the bees knees for me. @DirectXMan12
https://github.com/DirectXMan12 said to create another issue. Did anyone
do this already?

Googled around, hoping at least someone had already created a Schema so I
could get to work, but this is all I could find:
https://github.com/jbeda/kubernetes-detached/tree/master/api/doc


You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
#14987 (comment),
or mute the thread
https://github.com/notifications/unsubscribe-auth/ABG_p6s9mYUMCtlxXUaSCLuVzDBVH8i9ks5qvoW4gaJpZM4GIFPd
.

@joelharkes

This comment has been minimized.

Show comment
Hide comment

joelharkes commented Feb 17, 2017

@garethr

This comment has been minimized.

Show comment
Hide comment
@garethr

garethr Jun 10, 2017

Contributor

@joelharkes it looks like that repository is no longer available? Any chance you have another link or a reference to how you generated it?

Contributor

garethr commented Jun 10, 2017

@joelharkes it looks like that repository is no longer available? Any chance you have another link or a reference to how you generated it?

@joelharkes

This comment has been minimized.

Show comment
Hide comment
@joelharkes

joelharkes Jun 10, 2017

I generated with nodejs based on documentation. Yea had to delete repo, because there was wrong stuff in there. I'll setup a new repo this week and send the link.

joelharkes commented Jun 10, 2017

I generated with nodejs based on documentation. Yea had to delete repo, because there was wrong stuff in there. I'll setup a new repo this week and send the link.

@joelharkes

This comment has been minimized.

Show comment
Hide comment
@joelharkes

joelharkes Jun 14, 2017

@garethr I added the repository here:
https://github.com/joelharkes/kubernetes-json-schema

Old links also work again :)

joelharkes commented Jun 14, 2017

@garethr I added the repository here:
https://github.com/joelharkes/kubernetes-json-schema

Old links also work again :)

@garethr

This comment has been minimized.

Show comment
Hide comment
@garethr

garethr Jun 18, 2017

Contributor

I've been doing some work around this as part of building some tooling for Kubernetes. I have some tools (open source soon) which can take OpenAPI specs and extract the JSON Schema in a useable manner.

I've just generated schemas for Kubernetes from version 1.5.0 until 1.6.6 and pushed them to:
https://github.com/garethr/kubernetes-json-schema

I independently hit on a similar approach to @joelharkes which I think is a good sign.

These are only lightly tested so far so I'd be interested if anyone else who needed them has a chance to take a look and see if they meet your requirements.

Contributor

garethr commented Jun 18, 2017

I've been doing some work around this as part of building some tooling for Kubernetes. I have some tools (open source soon) which can take OpenAPI specs and extract the JSON Schema in a useable manner.

I've just generated schemas for Kubernetes from version 1.5.0 until 1.6.6 and pushed them to:
https://github.com/garethr/kubernetes-json-schema

I independently hit on a similar approach to @joelharkes which I think is a good sign.

These are only lightly tested so far so I'd be interested if anyone else who needed them has a chance to take a look and see if they meet your requirements.

@smarterclayton

This comment has been minimized.

Show comment
Hide comment
@smarterclayton

smarterclayton Jun 18, 2017

Contributor
Contributor

smarterclayton commented Jun 18, 2017

@garethr

This comment has been minimized.

Show comment
Hide comment
@garethr

garethr Jun 19, 2017

Contributor

@smarterclayton I've just pushed the tools used to generate the schemas, which should work against any OpenAPI endpoint. I've only lightly tested this so far but would appreciate any feedback if people try it out for that purpose: https://github.com/garethr/openapi2jsonschema

Contributor

garethr commented Jun 19, 2017

@smarterclayton I've just pushed the tools used to generate the schemas, which should work against any OpenAPI endpoint. I've only lightly tested this so far but would appreciate any feedback if people try it out for that purpose: https://github.com/garethr/openapi2jsonschema

@thesteve0

This comment has been minimized.

Show comment
Hide comment
@thesteve0

thesteve0 Jun 20, 2017

thesteve0 commented Jun 20, 2017

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment