Skip to content
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 · 22 comments
Closed

Need a structured Schema for the JSON #14987

thesteve0 opened this issue Oct 2, 2015 · 22 comments
Labels
priority/backlog Higher priority than priority/awaiting-more-evidence. sig/api-machinery Categorizes an issue or PR as relevant to SIG API Machinery.

Comments

@thesteve0
Copy link

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

@thesteve0
Copy link
Author

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
Copy link
Member

Forked from: #14294 (comment)

@bgrant0607 bgrant0607 added priority/backlog Higher priority than priority/awaiting-more-evidence. sig/api-machinery Categorizes an issue or PR as relevant to SIG API Machinery. and removed team/api labels Oct 3, 2015
@bgrant0607
Copy link
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?

@thesteve0
Copy link
Author

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
Copy link
Author

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
Copy link
Member

lavalamp commented Oct 5, 2015

I thought swagger did output json-schema?

Isn't this json-schema?

https://github.com/kubernetes/kubernetes/blob/gh-pages/swagger-spec/api/v1/index.html#L12438

Just ignore everything but the 'models': https://github.com/kubernetes/kubernetes/blob/gh-pages/swagger-spec/api/v1/index.html#L10955

@lavalamp
Copy link
Member

lavalamp commented Oct 5, 2015

Please reopen if this isn't a satisfactory answer.

@lavalamp lavalamp closed this as completed Oct 5, 2015
@DirectXMan12
Copy link
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

@thesteve0
Copy link
Author

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
Copy link
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).

@thesteve0
Copy link
Author

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
Copy link

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
Copy link
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
.

@joelharkes
Copy link

@garethr
Copy link
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
Copy link

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
Copy link

joelharkes commented Jun 14, 2017

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

Old links also work again :)

@garethr
Copy link
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
Copy link
Contributor

smarterclayton commented Jun 18, 2017 via email

@garethr
Copy link
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
Copy link
Author

thesteve0 commented Jun 20, 2017 via email

@reitzig
Copy link

reitzig commented Aug 5, 2021

Maintenance seems to have moved via instrumenta/kubernetes-json-schema (which is hosted on kubernetesjsonschema.dev) to yannh/kubernetes-json-schema (which doesn't seem to be hosted similarly).

Maybe an integration into the kubernetes organisation would make sense after all, so as to have a reliable, sustainably location.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
priority/backlog Higher priority than priority/awaiting-more-evidence. sig/api-machinery Categorizes an issue or PR as relevant to SIG API Machinery.
Projects
None yet
Development

No branches or pull requests

10 participants