Regular Expressions and Types


#1

It could be nice to be able to factor out regular expressions and give them a display name and description. This would enable a API designer to create his own “types” for URI and query parameters. It would also lead to better documentation, since you don’t have to repeat how a given regular expression acts in every description. It would also make it possible to easily include a lot of common regular expression types like: URI, e-mail, Data URI, ISO8601 date, JS identifier, etc.

What do you think?


#2

I guess you can split it up in two proposals. A way to describe patterns, example:

/files:
  get:
    queryParameters:
      mime:
        displayName: Filter Mime Type
        description: Only see files with a certain type.
        pattern:
          displayName: Mime Type
          description: Indicates the file type.
          regexp: "[\\w.+-]+/[\\w.+-]+"

And a method of referencing generic definitions. Example using YAML references (and inspired by JSON Schema):

definitions:
  - &simpleIdentifier "[A-Za-z_][\\w]+"
  - &mimeType
      displayName: Mime Type
      description: Indicates the file type.
      regexp: "[\\w.+-]+/[\\w.+-]+"

/files:
  get:
    queryParameters:
      mime:
        pattern: *mimeType
      name:
        pattern: *simpleIdentifier

#3

Pretty nice. Definitely worth considering. It’s like resourceTypes and traits and securitySchemes, only for scalars. Is there a better name than definitions? scalarTypes, perhaps?


#4

Yes, scalarTypes is a much better name. I’m all in for that.