Re: [scim] draft-shahzad-scim-device-model-00

[Brian Demers <[e-mail]>]

Great stuff Eliot!

I know nothing of the Device space, please forgive my ignorance if my
suggestions conflict with other established patterns/models in this space.

>From a developer usability perspective, I think the schema could be tweaked
slightly to reduce its nesting and verbosity a bit, particularly in
SCIM_endpoint_extension_schema.json (though much of this is personal
opinion, so take it with a grain of salt)

The JSON path to a few of these properties could be reduced, for example,
the properties:
urn:ietf:params:scim:schemas:extension:Endpoints:2.0:Device.onboarding.onboardingAppUrl
urn:ietf:params:scim:schemas:extension:Endpoints:2.0:Device.deviceControl.deviceControlApps.deviceControlAppUrl

Contain extra levels of nesting that may require additional documentation
and more code for the developer. In some languages, you would need to do
extra null checks to traverse the object graph.

Sometimes this can be avoided by flattening out the objects, where the
above look something like:
urn:ietf:params:scim:schemas:extension:Endpoints:2.0:Device.onboardingAppUrl
urn:ietf:params:scim:schemas:extension:Endpoints:2.0:Device.deviceControlApps[].deviceControlAppUrl

The `deviceControlApps` is an array which means some level of nesting is
required, but the names could still be tweaked to reduce the verbosity; the
nested structure should already provide enough context for each level,
maybe something like:
urn:ietf:params:scim:schemas:extension:Endpoints:2.0:Device.controlApps[].url

So the pseudo code in a verbose language like Java could be reduced from
something like:

```
var deviceControl = device.getDeviceControl();
// check if deviceControl is null, throw error

List<DeviceControlApp> apps = deviceControl.getDeviceControlApps();

//iterate over apps, and get the URLs
app.getDeviceControlAppUrl();
```

To something like:

```
List<DeviceControlApp> apps = device.getControlApps();

//iterate over apps, and get the URLs
app.getUrl();
```

As far as the actual schema format, similar to what Phillip mentioned, they
probably should be defined in the SCIM schema format (not to be confused
with XML schema).
https://www.rfc-editor.org/rfc/rfc7643.html#section-7

(unofficial copies of various schema)
https://github.com/apache/directory-scimple/tree/develop/scim-spec/scim-spec-schema/src/main/resources/schemas

On Thu, Oct 27, 2022 at 7:49 AM Eliot Lear <[e-mail]> wrote:

> Hi Phil,
>
> Thanks so much for your feedback.  We'll have more detailed answers in
> due course, but I want to call out one point now:
>
> On 26.10.22 20:12, Phillip Hunt wrote:
> >
> > Note: I have written a JSON Schema definition for SCIM’s core and
> > protocol and it is available in github at:
> > https://github.com/i2-open/i2scim/tree/master/spec/schema
> >
> > To the group at large, now that “schema” in JSON is no longer a dirty
> > word, I would think it might be interesting using JSON Schema at some
> > point in the future. The only issue at this stage, is that SCIM’s
> > discovery mechanism doesn’t use JSON Schema and would be a major
> > change.  Maintaining both formats would be a pain for implementers.
> >
> I wasn't explicit in my last message, but the draft is.  We're not doing
> XML.  If that's a problem for people, we should talk about it.  If
> someone else wants to convert what we end up with into XML Schema, I
> wouldn't object, but to me at least, it's like being forced to mow
> someone else's lawn.
>
> What I do think important is that we formalize the schema in a
> description language (props to XML schema people for really having
> gotten that ball rolling long ago), and that the description language be
> a canonical form of the schema that can be validated. The Python JSON
> schema validator is actually a pleasure to use for at least simple stuff.
>
> To this end, I'm very pleased to see your progress on Github.
>
> But there are some problems with JSON Schema that, quite frankly, annoy
> the crap out of me, and as this is a -00 draft, we can make lots of
> changes.  One change we could make would be to move to OpenAPI YAML.  I
> won't claim to be an expert on either JSON Schema OR OpenAPI, but at
> least the latter allows comments and multiline descriptions.
>
> We have a rough non-normalized version of the same schema in OpenAPI
> that can be found at
> https://github.com/iot-onboarding/scim-devices/scim.yml.
>
> I think this is food for thought.
>
> Eliot
>
>
>
> _______________________________________________
> scim mailing list
> [e-mail]
> https://www.ietf.org/mailman/listinfo/scim
>