github.com/josephspurrier/go-swagger@v0.2.1-0.20221129144919-1f672a142a00/docs/use/spec/strfmt.md (about)

     1  # swagger:strfmt
     2  
     3  A **swagger:strfmt** annotation names a type as a string formatter. The name is mandatory and that is
     4  what will be used as format name for this particular string format.
     5  String formats should only be used for **very** well known formats.
     6  
     7  <!-- more -->
     8  
     9  String formats are well-known items. These imply a common well-documented set of formats that can be validated. The toolkit allows for creating your own string formats too.
    10  
    11  To create a custom string format you need to create a type that implements the (Unm/M)arshalText interfaces and the sql Scan and sql Value interfaces.  The SQL interfaces are not strictly necessary but allow other people to use the string format in structs that are used with databases
    12  
    13  The default string formats for this toolkit are:
    14  
    15  * uuid, uuid3, uuid4, uuid5
    16  * email
    17  * uri (absolute)
    18  * hostname
    19  * ipv4
    20  * ipv6
    21  * credit card
    22  * isbn, isbn10, isbn13
    23  * social security number
    24  * hexcolor
    25  * rgbcolor
    26  * date
    27  * date-time
    28  * duration
    29  * password
    30  * custom string formats
    31  
    32  ##### Syntax:
    33  
    34  ```
    35  swagger:strfmt [name]
    36  ```
    37  
    38  ##### Example:
    39  
    40  ```go
    41  func init() {
    42    eml := Email("")
    43    Default.Add("email", &eml, govalidator.IsEmail)
    44  }
    45  
    46  // Email represents the email string format as specified by the json schema spec
    47  //
    48  // swagger:strfmt email
    49  type Email string
    50  
    51  // MarshalText turns this instance into text
    52  func (e Email) MarshalText() ([]byte, error) {
    53  	return []byte(string(e)), nil
    54  }
    55  
    56  // UnmarshalText hydrates this instance from text
    57  func (e *Email) UnmarshalText(data []byte) error { // validation is performed later on
    58  	*e = Email(string(data))
    59  	return nil
    60  }
    61  
    62  func (b *Email) Scan(raw interface{}) error {
    63  	switch v := raw.(type) {
    64  	case []byte:
    65  		*b = Email(string(v))
    66  	case string:
    67  		*b = Email(v)
    68  	default:
    69  		return fmt.Errorf("cannot sql.Scan() strfmt.Email from: %#v", v)
    70  	}
    71  
    72  	return nil
    73  }
    74  
    75  func (b Email) Value() (driver.Value, error) {
    76  	return driver.Value(string(b)), nil
    77  }
    78  ```
    79  
    80  ##### Result:
    81  
    82  ```yaml
    83  ---
    84  definitions:
    85    user:
    86      properties:
    87        email:
    88          type: string
    89          format: email
    90  ```