I am not sure if we’re talking actual types or the fields themselves?

If it’s just the types, that’s easy enough. Following your example the user module would look like this:

defmodule App.UserSchema do
  alias App.Shared.Types

  @type user_result :: {:ok, Types.generic_id()} | {:error, any()}
end

Not sure about inheritance, but since we only can define types within modules, means we need to use modules as containers for types

My intent is to only write truly reusable things in one place, maybe meaningfully grouped in multiple places, in order to prevent “bad” duplication (aka knowledge duplication), as opposed to “ok”/coincidental duplication, which I’m ok with. So it seems like these types are better reside somewhere meaningful

E.g. when I work with data which has specific shape/types defined for this data, then I handle this data in some other place — it is useful to be able to refer to a type of a specific field for this data and not to duplicate the type and then keep it in sync

For when to write typespecs — I figured it’s a whole new topic, which I’ll investigate further, e.g. I read it is recommended to only write typespecs for public functions

That’s practically what I imagined

Actual types. This is what I expected, but wanted to confirm. The 2nd case is more vague though: we already export struct type, but we can not refer to a field type of this struct, this requires defining it in a separate public type near this struct (but maybe in practice it is not an issue at all)

Great points! For sure I’ll be keeping details to where they belong

Try to imagine similar way of thinking … Would you like to write dozens or hundreds of Ecto.Schema just to have them in one place? For sure there is no rule to cover all edge cases, but in general we rather avoid such practices.

Firstly all struct related types should be defined in struct’s module. It’s no shame to have a public type for a single field just to reuse said type somewhere else as long as we speak about same data i.e. it’s fine to use field’s type somewhere in code especially when we write typespec for private functions for dialyzer tool or so.

However using same type just because it’s typespec matches specific needs (like a generic keyword() type) is incorrect as developer working with your library would think that only data from said struct are seen as valid / supported.

# Here we have struct and all related typespec in one place.
# Structs may be big for sure, but definitely not like all types in one place.
defmodule MyLib.SomeStruct do
  # …

  defstruct # …

  @typedoc "…"
  @type t :: %__MODULE__{
    some_field: some_field(),
    # …
  }

  @typedoc "…"
  @type some_field :: # …

  # …
end

# Generally I recommend to write types as high as possible
# i.e. it would be weird if a parent module would use a type from sub module
# as the data is not strictly related to anything (like in structs)
# so the type should be defined in highest parent module which uses it
# or a parent module which groups sub modules using said type
defmodule MyLib.Utils do
  # …

  @typedoc "…"
  @type commonly_used_data_type_not_related_to_any_struct :: # …

  # …
end

In example above I would move the type definition from MyLib.Utils to MyLib if MyLib or MyLib.OtherModule would use it. Otherwise it’s in good place.

Of course there may be an edge case. Let’s say that you document an API and then Utils (more generic code) would use types from it.

defmodule MyApp.Utils do
  # …

  @spec some_func(MyApp.API.V1.APIObjectNotRelatedToAnyStruct.type_name()) :: # …

  # …
end

That’s why there is no one rule to write typespec. Generally you put types in order:

1. If it’s related to a struct then in struct module
2. If it’s related to some specific module like when documenting API which does not need it’s struct
3. In top Utils-like module as in above example