kubernetes/kubernetes

Need a structured Schema for the JSON

thesteve0 opened this issue · 22 comments

thesteve0 commented

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

thesteve0 commented

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 commented

@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 commented

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

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 commented

Please reopen if this isn't a satisfactory answer.

DirectXMan12 commented

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 commented

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 commented

@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 commented

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 commented

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 commented

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
.

  • 👍1
garethr commented

@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 commented

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

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

Old links also work again :)

garethr commented

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.

  • 👍2
smarterclayton commented
garethr commented

@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

  • 👍1
thesteve0 commented
reitzig commented

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.

  • 👍3