Currently the out-of-the-box tv4 validation errors can be a bit cryptic, like:

JSON schema error in item: Data does not match any schemas from "oneOf"

We could provide custom error messages at least for the common cases.

See geraintluff/tv4#115 (comment)

I'd love to get a clear picture of the current User schema for requests made to https://api.thegrid.io/user.

The only documentation I can find is for https://passport.thegrid.io/api/user which has significantly less properties than the JSON response I'm seeing.

I'm hesitant to share what properties are present since I'm not sure if I have anything "special" due to being on staff at The Grid.

All I need for each property is its name, type, and if its required.

Please help!

Currently only GitHub and Twitter are listed.

also should probably be listed as required: https://github.com/the-grid/apis/issues/63

Right now we just raw-dump the schemas into the blueprint. This is useful-ish, but things like $ref: someother-schema is confusing.

References should be resolved, and then put links into the HTML to navigate up/down between these. For single base definitions (which are usually very short) it might be nicer to inline.
Also, there should probably be a link to the schema itself (in .yml and .json format), so people see where it comes from.

Came up in #26

I think the information on updating users is unclear.

"required" suggests that email address must be provided whenever an update is made. Is that only the case if the email address is being updated?

If I'm interpreting the User schema correctly, email address is not required and may not be present in order to send back in a PUT request anyway.

Some endpoints are documented as returning the new/updated resource (as is conventional) when making a POST or PUT request, but others aren't.

Is the documentation incorrect?

This is present in the response when making a GET request to https://passport.thegrid.io/api/user, but isn't documented or shown in the schema.

This appears to be the authentication scopes listed here: http://developer.thegrid.io/authentication.html

Can I assume that this is optional? It's not present when making a request to https://passport.thegrid.io/api/user/{id}.

Am I correct in thinking that it's not possible to create a fully configured site in a POST request?

That is, with more than just the name and repo fields but also including site configuration data.

It seems as if a site must first be created and then configured via a PUT request.

https://github.com/tripit/slate

Just to make it clear people can file issues and pull requests with fixes

There's no easy way to get back to the home page or other site sections.

Does this still exist? I don't see it in any API responses. If it does, what is its purpose?

https://github.com/the-grid/apidocs/blob/master/schemata/imagemeasurements.yaml

should this schema be somewhere be on the html docs too, or is it and I just didn't find it?

I just got my beta-access and have been trying out the various tools. But I study computer information systems and would really like to know more about the developer side of things. Also a lot of people getting beta-access now are very disappointed about your progress the last year and still yell "scam!" which I can sort of understand.

You should be more honest to us early investors about when you think The Grid will be commercially ready and what you plan to do until then. Or is it published somewhere that I just haven´t found yet?

For other design systems to preheat imgflo, etc. https://github.com/the-grid/pipeline/issues/10

These are quite standard so I propose we add them to the schema as discussed with @bergie

var title: String?
var context: String?
var datePublished: String?
var dateModified: String?
var description: String?

http://developer.thegrid.io/schema/metadata.json

hannes [4:31 PM]
bergie: if I do multiple POST /share with the same url, sending images, should they end up in the same post? (edited)

bergie [4:34 PM]
hannes no, unless you use the same item id

hannes [4:36 PM]
bergie: would that be something like an itemId part?

hannes [4:36 PM]
can’t find info here: http://developer.thegrid.io/api.html#content-management-share-post

bergie [4:37 PM]
item and index

hannes [1:08 PM]
bergie: is it possible to share a URL to an item? docs suggest otherwise http://developer.thegrid.io/api.html#content> -management-share-post

hannes [1:08 PM]
only {
"url": "http://example.net/some-article"
}

bergie [1:09 PM]
every share accepts item and index

Is this missing in the schema, or obsolete in the API?

edit: Or is this a convenience-thing that only exists when querying the list of all items?

I don't see block.cover documented http://developer.thegrid.io/api.html#content-management-item

Is there a key for faces + saliency bbox, or do I need to derive that? @automata

I need to decide where/how to save user-defined focus rectangle

• block.metadata.coverPrefs.scene -- ok?
• {x,y,width,height} -- top-left, bottom-right points of original pixels ok?

What's the status of the API according to http://jsonapi.org?

Is it compliant and/or are there plans to make it that way if not already?

https://github.com/the-grid/apidocs/blob/master/schemata/job.yaml#L35-L37

Is there a schema for the structure?

http://developer.thegrid.io/designsystem.html

How do we define that in the site config yml / chrome? Will other design systems define their own spectra for chrome to tweak?

as in GET /item?measurements=param1,param2,param3

The Metadata schema doesn't describe any required properties.

Does this mean that none of them are required?

Hitting POST /publish can result in 422 Unprocessable entity, e.g. if the item is empty or was already published in that version. All different cases should be documented.

"rgbcolor": {
  "description": "RGB color",
  "format": "rgbcolor",
  "pattern": "^#([a-fA-F0-9]{6}|[a-fA-F0-9]{3})$",
  "example": "#aa33cc",
  "type": "string"
},

I would expect this to have red, green, and blue properties.

API data examples needed to wire up cover editor:

• share a tweet, add a comment
• share a tweet with image, add a comment
• share a video
• share an article (image, title, desc), fix spammy title, expand to full post

cc @bergie @jxnblk

This is present in the response when making a GET request to https://passport.thegrid.io/api/user, but isn't documented or shown in the schema.

Unless I'm mistaken it's the UUID of the app used to make the request.

It's not present when making a request to https://passport.thegrid.io/api/user/{id}, so can I assume that it's optional?

{
    aps =     {
        "content-available" = 1;
    };
    id = "97de34d7-c2c5-42b1-9fa4-341faffdf3c6";
    item = "7518ebf7-1f88-4f2a-a5db-c0c6c275e921";
    type = "finished_block_measurement";
}

{
    aps =     {
        "content-available" = 1;
    };
    id = "7518ebf7-1f88-4f2a-a5db-c0c6c275e921";
    type = "new_item";
}

id and item are not in the specification.

Just out of date.

Apparently there is an endpoint at api.thegrid.io/user that returns different information than passport.thegrid.io/api/user

I assume that this means that the page on Passport is now out of date.

Should all user operations should be made against https://api.thegrid.io instead of https://passport.thegrid.io?

We should provide the info needed to do this.

For example, from Twitter: https://dev.twitter.com/overview/api/ssl

Key part of The Grid, and different from other platforms. Missing explanation can lead to misunderstanding later.

Key part of The Grid, and different from other platforms. Missing explanation can lead to misunderstanding later.

Currently we use a stock aglio template.

Should at least:

• Tweak color, typography to match The Grid brand
• Add The Grid logo, links out to https://thegrid.io

Example:
http://developer.thegrid.io/schema/notification.json
owner, repo, name do not exist in the spec

[id: 94abb08d-6822-4a37-92b3-e23003e5f187, owner: 368c03f5-d778-420c-b14d-58fd788912e2, repo: the-domains/sandbox, type: new_site, name: sandbox, aps: {
    "content-available" = 1;
}]

There's a mention of notification channels in the current docs but it doesn't go into any detail.

I see some JSON schema information displayed like this:

In particular, I'm not sure if the "$ref": "base.json#/definitions/uuid" part is supposed to be displayed that way or if something has gone wrong with page rendering.

If it is correct, could someone point me to where base.json lives?