Format Registry documentation is not accurate / well published

[Bellangelo]

Closes #3703

i have changed the format of the base_type in the produced JSON to array for all the formats since I think we should be consistent with the property types between the formats.

[mikekistler]

I think there is the potential for confusion here.

[mikekistler]

I think this could create some confusion. The intent in this particular case is that the sf-integer format can be applied to either type: integer or type: number. Since OAS 3.1 the type value can be an array, so a reader might think that type: [integer, number] is the base type for this format.

[Bellangelo]

Based on what we use more it looks like this is indeed the correct format. You can check also decimal and decimal128.

One more note, I am not so sure that the representations in these files are THAT important. The reason is that these files seem to just be for building the page and not for documentation. Which means that we mostly care for the end result and how the data will appear when rendered.

[mikekistler]

I agree with this:

we mostly care for the end result and how the data will appear when rendered.

and thanks for the link to the decimal format because that shows how problematic the change actually is.

I would argue that this is not how we want the data to appear, so the array format just looks wrong to me.

If anything, I think we should be going the other direction, to make all these just a comma-separated string.

[Bellangelo]

@mikekistler That's what the PR fixes. They will appear as string, number. I don't fully agree that the users might be confused but if others agree with you we can change the others instead of the sf-integer

[handrews]

@Bellangelo I think what @mikekistler is getting at is that we just need the existing string, number to be rendered as string, numer, rather than rendering it as something that looks like a tuple with first a string and then a number.

[Bellangelo]

Hi @handrews and @mikekistler, I think there is a misunderstanding here, so I will try to explain the situation the best I can.
So, the line that @mikekistler commented on is a variable for the Liquid template engine that Jekyll uses. The reason why the sf-integer and the decimal appear different is that the sf-integer sets the variable type to a string, while the other to an array. Liquid by default joins array's item together without any separator. This is solved by this line which overrides the default behavior and instead uses the separator that we want, a comma with a space.
Did you test it and had different results?

While we could easily just use the string instead, so keeping the sf-integer as is and changing the rest, the reason I persist on this is that it feels kind of weird to me that the produced JSON would have a base_type which is a string but it contains actually 2 values.
From this point, there are 2 ways to go to:

1. You agree with the point i made on the JSON part: Then if we keep the variable type as a string we would need to create a more complex filter as we would need to split the string and generate a valid JSON array.
2. You don't agree with the point I made on the JSON part: Then I revert the changes on how we produce the JSON and I change every format that uses an array.
3. Of course, there is a secret 3rd option which you can just suggest something that i missed.

PS. Sorry for insisting on a minor issue.

[handrews]

@Bellangelo Ah, yes I see, thank you for clarifying! I agree that sf-integer should be an array here, (matching how it is in decimal, for example). I got confused thinking that all of the others did not wrap that list in an array. But they do. My apologies! I read through this too quickly.

@mikekistler I think this is correct, or at least it's the same as the other formats that use either of two types. If this isn't the way we want to structure type alternative lists, we should probably sort that out separately from this bugfix.

[mikekistler]

Thanks for the extended explanation @Bellangelo! This looks good then.

[mikekistler]

Looks good! 👍

Thanks for the fix!