Record level restrictions

[codygustafson]

FBS has needed the functionality in the past to differentiate between null values and a restricted values for a particular listing record. This is in regards to fields that have permissions based on the record you are viewing. As an example: If a developer is accessing the API on behalf of an agent and that agent does not have access to view the ExpirationDate in a different office, It should be displayed as a permissions issue. "null" is not the same thing since it indicates there is no value. In this case, there is a value but the authorized user of the API does not have permission to see it.

FBS has adopted Core.Permissions to handle this use case for our members. In the past, I believed this was fine since it is part of the OData spec. But now that we would like to start being strict with metadata and which fields display on a listing.

Properties that are not available, for example due to permissions, are not returned. 

This may contradict some of the previous testing we discussed about metadata strictness. I would like to officially support this functionality within RESO. If there is another way to show this data as restricted, I'm all ears. I'm not particularly a fan of this method but since it was the OData definition I found and it fit our use case, we implemented it.

[EnFinlay]

I'm on board with this, it's something we could use on our end as well.

To be clear, the JSON payload returned in the ExpirationDate example would look like the below?

{
  "ListingKey": "abc123",
  ...
  "ExpirationDate": "Core.Permissions'None'"
}

[codygustafson]

Yeah, that is one reason I am open to different methods of doing this. On the flip side, "Core.Permissions'None'" is not a Date - exposing something as not described in the metadata seems like a hard no. Note that OData doesn't call this a "field", it is an "instance annotation". The field in this case does not come through via the payload but the instance annotation shows the field is missing because you do not have permission to view it.

[EnFinlay]

That's a good point about None not being a Date. Definitely a hard no on that.

If that's the OData way, seems foolish to reinvent the wheel.

[darnjo]

It's interesting OData decided to use an annotation in the JSON payload to express this. It also makes the data shape a bit irregular since the underlying field is removed from the payload entirely and not just left null.

One of the goals has been to avoid additional OData dependencies, when possible. Since this is at the record level, I don't know a good way to do that without adding something to the payload.

I guess there are two choices - use what's already there or create another mechanism for it.

Using OData's approach means that the consumer would need to check for the instance annotation before trying to parse the payload if the code wasn't able to handle a set of fields being missing on a per record basis. This also makes something like JSON Schema validation interesting, unless every field aside from the key was set as optional.

Similar to Eric, I'm not a huge fan of trying to create something new to handle this.

I kind of wish OData would have just added something like @FieldRestrictions: [] with a list of fields or permissions objects containing field names that are to be restricted, if any, and not changing the data shape.

We can definitely discuss it further. I'm curious whether others have a need to indicate that a record was restricted rather than just nulling it out or returning an empty list in collection-based fields?

[codygustafson]

@FieldRestrictions: [] does sound fairly elegant.

[EnFinlay]

@FieldRestrictions: [] sounds better than changing the shape arbitrarily.